< Rocky> im using starRocks 4 1 1 why do youl support one cl StarRocks #questions-and-troubleshooting

<@U0A71G31CDV> im using starRocks 4.1.1 why do you...

Eliezer Talker

07/02/2026, 2:21 PM

@Rocky im using starRocks 4.1.1 why do youl support "one cluster has one run mode" why cant the same cluster allow us to query tables in starRocks or tables in starRocks format that are stored in s3 ?

Rocky

07/02/2026, 2:22 PM

In StarRocks 4.1.1 (and the 4.x series), the system continues to use a mutually exclusive Run Mode (

shared_nothing

shared_data

) primarily because of how the Metadata Layer and Node Management are designed. However, you can query StarRocks-formatted data on S3 from a Shared-Nothing cluster using a feature called Data Tiering. Here is the breakdown of why the run modes are separate and how you can achieve your goal. 1. The Architectural Reason: Metadata Paradigms The two modes use fundamentally different logic for managing data reliability and location: * Shared-Nothing (SN): The Frontend (FE) tracks Tablets mapped to specific Backend (BE) nodes. It manages physical replicas (e.g., 3 copies) and ensures consistency across those specific disks. If a node fails, the FE initiates a "clone" operation between nodes. * Shared-Data (SD): The FE manages tablets as Objects in S3/Remote Storage. The Compute Nodes (CNs) are stateless. There are no "replicas" in StarRocks because durability is offloaded to S3. The metadata service tracks object versions rather than node-to-disk mappings. Mixing these in one cluster would require the FE to run two separate metadata engines and scheduling logics simultaneously, which adds significant complexity to the core engine. 2. How to Query S3 in a Shared-Nothing Cluster If you are in a Shared-Nothing cluster but want to store and query data on S3, you have two main options: * Option A: Data Tiering (Hierarchical Storage) This is likely what you are looking for. In a Shared-Nothing cluster, you can set a Storage Policy to move "cold" data to S3. * The data remains in the internal StarRocks format. * StarRocks handles the movement and querying automatically. * This allows you to keep "hot" data on local SSDs and "cold" data on S3 within the same cluster. * Option B: External Catalogs If the data in S3 is in open formats (Parquet, ORC, Iceberg, Delta Lake), you can use an External Catalog. Both SN and SD clusters can query these equally well. 3. StarRocks 4.1 Improvements In StarRocks 4.1, while the run modes are still distinct, several features bridge the gap: * Unified Catalog: Allows you to query various data lake formats (Iceberg, Hive, etc.) through a single catalog entry, making the "external" data feel more like "internal" data. * Compute Nodes (CN) in SN: You can add stateless CN nodes to a Shared-Nothing cluster. While they don't store local data, they can be used to scale out the "computation" of queries against S3 (External Catalogs) without affecting the local storage BEs. Summary Table Capability | Shared-Nothing (SN) | Shared-Data (SD) Primary Storage | Local Disks (BEs) | S3/Object Storage (CNs) StarRocks Format on S3 | Yes (via Data Tiering) | Yes (Native) Open Formats on S3 | Yes (via External Catalogs) | Yes (via External Catalogs) Elastic Scaling | Slower (requires rebalance) | Instant (Stateless CNs) Recommendation: If you want a cluster that mostly uses local storage but has some tables/partitions on S3 in StarRocks format, stay in Shared-Nothing and use Storage Policies (Data Tiering). If you want everything on S3 by default, use Shared-Data. References • deployment/shared_data/feature-support-shared-data.md • administration/management/FE_configuration.md • quick_start/shared-data.md

Rocky

07/02/2026, 2:22 PM

In StarRocks v4.1.1, the restriction of "one cluster, one run mode" exists because the underlying storage engine and metadata management for internal tables are fundamentally different between the two modes. Why the restriction exists The two modes are designed around different "sources of truth" for data: * Shared-nothing (
shared_nothing
): The FE manages data distribution based on physical replicas. It tracks which BE nodes hold which specific copies of tablets (usually 3 replicas). The storage engine on the BE is optimized for local disk I/O and peer-to-peer data replication. * Shared-data (
shared_data
): The FE manages data as objects on S3/Remote Storage. There are no "replicas" in the traditional sense; instead, the FE tracks object paths. The Compute Nodes (CNs) are stateless and rely on a local cache to mimic the performance of local disks. Mixing these two within a single internal catalog would require the FE to run two parallel, conflicting metadata managers and the backends to support two different storage abstractions (Tablet-on-Local vs. Tablet-on-Object) for the same table engine. To maintain stability and performance, StarRocks currently treats these as mutually exclusive architectures for internal tables. How to query both internal and S3 data Even with this restriction, you can achieve your goal of querying both types of data in the same cluster depending on your setup: 1. If you use Shared-data mode: * This is the recommended mode if you want the best of both worlds. * Internal Tables on S3: All internal tables are stored in S3/MinIO/GCS by default. * Local Disk Performance: You can enable the Data Cache (

"datacache.enable" = "true"

) on your tables. This keeps "hot" data on local disks, giving you the query speed of a shared-nothing cluster while the actual data lives on S3. * Querying S3 Files: You can still query raw files (Parquet, ORC, etc.) on S3 using

FILES()

or External Catalogs (Iceberg, Hive). 2. If you use Shared-nothing mode: * Internal Tables: These are stored on local disks only. * Querying S3: You can query tables in S3 via External Catalogs (Iceberg, Hive, Hudi) or the

FILES()

table function. * The Catch: You cannot currently create a "StarRocks format" internal table that resides on S3 in this mode. Summary If you need internal tables to reside on S3, you should deploy your cluster in Shared-data mode. If you are worried about performance, the Data Cache feature is specifically designed to bridge the gap by automatically caching S3 data onto local BE/CN disks. /CN disks for sub-second query performance. performance. For further architectural details, you can refer to the StarRocks Shared-data documentation. References • deployment/shared_data/s3.md

Eliezer Talker

07/02/2026, 2:28 PM

@Rocky my use case was having native iceberg tables with hot data and after x day move it to s3 in iceberg format. now we got another use case where we need to support full test search and my data is some columns and one of the columns is a big json. now this would require if im not wrong having this as a spearate table -> but if I move it it to iceberg format to s3 then how can we query text search on it -> so I thought maybe only this table will be moved to s3 but in starRocks format

Rocky

07/02/2026, 2:28 PM

To support your use case of Full-Text Search (FTS) on data stored in S3, you should use Shared-data mode rather than moving data to an external Iceberg format. Here is why your proposed "move to Iceberg" workflow conflicts with FTS, and how to solve it: 1. The FTS Limitation: Internal vs. External * Inverted Indexes (FTS) are a feature of StarRocks' internal storage engine. They are not supported for External Tables (Iceberg, Hive, etc.). * If you move your "cold" data into Iceberg format on S3, you can still query it, but you will lose the ability to use the

MATCH

MATCH_ALL

predicates for fast full-text search. The query would have to scan the entire JSON string using

LIKE

, which is very slow for large datasets. 2. The Solution: Shared-data Mode (Internal Tables on S3) Since you are looking at v4.1.1 (which introduces the built-in inverted index), you can have the best of both worlds by running the cluster in Shared-data mode: * Storage: All your internal tables are stored on S3 in StarRocks' native format. * Full-Text Search: v4.1.1 introduces a native "built-in" inverted index implementation that specifically supports Shared-data clusters. You can create an index on your JSON/String column even though the data resides on S3. * Performance (Hot/Cold): Instead of moving data between formats (Internal -> Iceberg), you use the Data Cache. * Hot Data: Stays in the local cache on the CN (Compute Node) disks for sub-second performance. * Cold Data: Evicted from the cache but remains on S3. You can still query it with FTS using the built-in inverted index, which StarRocks will pull from S3 as needed. 3. Handling the "Big JSON" For a large JSON column, StarRocks inverted indexes work on

VARCHAR

STRING

types. * Recommendation: If the JSON is very large, consider extracting the specific fields you need to search into a separate

STRING

column (or using a Generated Column) and applying the

INDEX ... USING GIN

on that column. * In v4.1, you can create the index like this in a Shared-data cluster:

Copy code

sql
    CREATE TABLE search_table (
        id BIGINT,
        json_data STRING,
        -- Indexing the JSON string for full-text search
        INDEX idx_fts (json_data) USING GIN("parser" = "english", "imp_lib" = "builtin")
    )
    DISTRIBUTED BY HASH(id);

Summary for your use case If you require Full-Text Search on data that eventually lives on S3: 1. Do not move it to Iceberg format if you still need FTS performance. 2. Use Shared-data mode for the cluster. 3. Store the data in a StarRocks Internal Table (which natively uses S3 in this mode). 4. Use the built-in inverted index (available in v4.1+) to enable FTS on that S3-backed data. References • table_design/indexes/inverted_index.md • deployment/shared_data/s3.md References • table_design/indexes/inverted_index.md

Eliezer Talker

07/02/2026, 2:32 PM

@Rocky but like I got many customers and many alerts so having it in cahce compute node is to expensive

Rocky

07/02/2026, 2:32 PM

It is a common misconception that Shared-data mode requires you to keep all your data in the Compute Node (CN) cache. In fact, StarRocks is designed specifically to solve the "expensive storage" problem you are describing. Here is how you can support many customers and alerts on S3 without the high cost of massive cache disks: 1. You don't have to cache everything In Shared-data mode, the S3 bucket is the only "source of truth." The local disks on your Compute Nodes are just for an optional "acceleration layer." * Cold Data stays in S3: If you have billions of rows of old alerts that are rarely accessed, you don't need to provision disk space for them on your CNs. * Queries still work: When you search for an old alert, StarRocks will fetch only the specific data blocks it needs directly from S3. * Performance: While reading from S3 is slower than local disk, StarRocks' built-in Inverted Index (v4.1+) makes this efficient. Instead of scanning the whole S3 file (like Iceberg would), the index tells StarRocks exactly which small blocks to download. 2. Automatic Hot/Cold Management (
partition_duration
) You can automate which data is "expensive" (cached) and which is "cheap" (S3-only) using table properties:

Copy code

sql
CREATE TABLE alerts (...)
PROPERTIES (
    "datacache.enable" = "true",
    "datacache.partition_duration" = "7 days" 
);

* Hot Data (Last 7 days): Automatically kept in the CN cache for sub-second search. * Cold Data (> 7 days): Automatically evicted from the local cache. It stays on S3, saving you money on compute node disk space. It remains searchable, but the first time you query it, StarRocks pulls it from S3. 3. Built-in Inverted Index is the key In StarRocks v4.1.1, the "built-in" inverted index implementation is designed for this exact architecture. * The index files themselves are stored in S3. * When you run a

MATCH

query on your big JSON column, StarRocks downloads the small index pieces first to find the relevant rows, then downloads only the specific data blocks containing those rows. * Cost vs. Iceberg: If you used Iceberg on S3, a full-text search would require a full table scan. This would result in massive S3 API call costs and data egress charges. StarRocks' native format with indexes is actually cheaper because it reads much less data from S3. Summary of the Strategy 1. Use Shared-data mode: Deploy with small, cost-effective local NVMe/SSD disks for the cache. 2. Use the Built-in Index: Create the index with

USING GIN("imp_lib" = "builtin")

. 3. Tune your Cache: Set

datacache.partition_duration

so only the most recent alerts (which get the most traffic) use the cache. This gives you the ability to search petabytes of data in S3 without paying for petabytes of high-performance local storage. References • table_design/indexes/inverted_index.md • deployment/shared_data/feature-support-shared-data.md • faq/shared_data_faq.md References • deployment/shared_data/feature-support-shared-data.md • table_design/indexes/inverted_index.md • faq/shared_data_faq.md

Eliezer Talker

07/02/2026, 2:36 PM

@Rocky we need to support full text search, but also support the ability to sort/filter by columns/by dates and so on

Rocky

07/02/2026, 2:36 PM

Yes, you can absolutely do both. Because you are using StarRocks internal tables (even though they are stored on S3 in Shared-data mode), you get the full power of a relational database alongside the Full-Text Search (FTS). In StarRocks v4.1.1, your queries can look like this:

Copy code

sql
SELECT customer_id, alert_time, json_payload
FROM alerts
WHERE alert_time >= '2023-10-01'           -- Standard Date Filter
  AND customer_id = 12345                  -- Columnar Filter
  AND json_payload MATCH 'connection error' -- Full-Text Search
ORDER BY alert_time DESC                   -- Sorting
LIMIT 50;

How StarRocks handles this efficiently on S3: 1. Multi-Index Intersection: StarRocks doesn't just pick one index. It will use the Zone Maps (min/max metadata) on the

alert_time

column to skip entire files on S3 that don't match your date range. Simultaneously, it uses the Inverted Index on the JSON column to find specific rows. It then intersects these results to download only the tiny fraction of data that matches all criteria. 2. Columnar Storage: Unlike a traditional search engine, StarRocks only reads the columns you actually need for your query. If you are filtering by

alert_time

and

customer_id

, it only fetches those small columns from S3 to perform the initial filtering before it ever touches the heavy "big JSON" column. 3. Sorting & Paging: Since this is a native OLAP engine,

ORDER BY

and

LIMIT

are highly optimized. It can perform a top-N sort across your compute nodes, which is much faster than fetching all matching rows and sorting them in an application. 4. Built-in Index for S3: In v4.1.1, you should use the built-in inverted index (

imp_lib

builtin

). It is specifically designed for Shared-data (S3) and supports features like

dict_gram_num

which speeds up partial word matches (e.g., matching

_error_

inside a long string) without needing to scan the whole S3 file. Recommendation for your "Big JSON" If your JSON is very large but you only need to search specific parts of it, you have two options: * Index the whole JSON: Use the

GIN

index on the JSON column. * Generated Columns (Optimized): If you frequently search a specific field (e.g.,

error_code

inside the JSON), you can create a Generated Column that extracts that field and put a standard index on it. This makes the search even faster and the index smaller. Summary By staying with Shared-data internal tables instead of raw Iceberg: * You save money: Data lives on S3. * You get speed: FTS + Date Filtering + Sorting all happen natively in the engine. * You get flexibility: You can run complex SQL that search engines or raw file formats struggle with. References • table_design/indexes/inverted_index.md • deployment/shared_data/feature-support-shared-data.md References • table_design/indexes/inverted_index.md • best_practices/query_tuning/schema_tuning.md

Eliezer Talker

07/02/2026, 2:40 PM

@Rocky dont people usually prefer hot data starRocks cold iceberg to not be locked into your proprietary format ? also do we risk tomorrow youl saying we need to pay youl ?

Rocky

07/02/2026, 2:41 PM

These are valid concerns. You are highlighting the classic trade-off in modern data architecture: Interoperability (Iceberg) vs. Performance/Features (Native Format). Here is a breakdown of why users choose one over the other and why the "lock-in" risk is lower than it might seem. 1. Why people choose Iceberg for Cold Data You are right—many people prefer Iceberg for cold data because: * Zero Lock-in: Any engine (Spark, Trino, Flink) can read the data. * Ecosystem: It’s the industry standard for a "Single Version of Truth." * Storage Costs: S3 storage is cheap. The Catch: Iceberg was designed as a table format for scan-heavy batch jobs. It does not natively support Inverted Indexes or the low-latency random access needed for a Google-like search experience on a "Big JSON" column. If you move your search use case to Iceberg, your queries will likely shift from milliseconds to tens of seconds (or minutes) because they have to scan all the files. 2. Why people choose StarRocks Native (Shared-data) Users choose the StarRocks internal format on S3 when they need features that open formats don't yet provide: * Full-Text Search (FTS): The Inverted Index is a specialized data structure that lives alongside the data. Currently, there is no cross-engine standard for "Inverted Indexes on Iceberg" that StarRocks and others can all share. * Performance: Native tables support advanced optimizations like Primary Key updates, Global Indexes, and built-in Inverted Indexes that make searching cold data on S3 feel like searching hot data in memory. 3. Addressing the "Lock-in" & "Pricing" Risk You asked: "do we risk tomorrow youl saying we need to pay youl?" * Open Source Governance: StarRocks is a Linux Foundation project and is licensed under Apache License 2.0. This means the source code is open, and the project is governed by a neutral foundation, not a single private company. No one can "turn off" your access to the software or suddenly demand payment for code that is already released under Apache 2.0. * It’s not a one-way street: Even if you store data in StarRocks' native format today, you are not trapped. You can "off-ramp" at any time: * EXPORT: You can export StarRocks tables back to Parquet/CSV on S3 whenever you want. * INSERT INTO Iceberg: You can run a command like

INSERT INTO iceberg_table SELECT * FROM sr_native_table

to move data from the proprietary format to the open format if you decide to change engines later. Summary Recommendation * Use Iceberg for data that needs to be shared with many different teams/tools and where "standard SQL filters" (date, ID) are enough. * Use StarRocks Native (Shared-data) for your Alerts + Big JSON search use case. The cost is the same (it’s just files on S3), but you get the Full-Text Search speed that Iceberg simply cannot provide today. If the search performance on Iceberg becomes "good enough" in the future, you can simply migrate the data out of the native format using an

INSERT INTO

command. References • table_design/indexes/inverted_index.md • sql-reference/sql-statements/data-export/EXPORT.md • data_source/catalog/iceberg/iceberg_catalog.md References • table_design/indexes/inverted_index.md • data_source/catalog/iceberg/iceberg_catalog.md • sql-reference/sql-statements/data-export/EXPORT.md

Eliezer Talker

07/02/2026, 2:49 PM

@Rocky ok a couple of more questions, we need sub second query time for hot data -> in this shared modal can we say keep in ssd last 30 days data, how does this work ?

Rocky

07/02/2026, 2:49 PM

In the Shared-data model (S3 storage), achieving sub-second latency for "hot" data while keeping "cold" data on S3 is handled by the Data Cache and the partition_duration
property. 1. How it works: The "30-Day" Window To keep the last 30 days of data on your SSDs, you set a table property during creation (or via

ALTER TABLE

Copy code

sql
CREATE TABLE alerts (
    alert_time DATETIME,
    ...
) 
PROPERTIES (
    "datacache.enable" = "true",
    "datacache.partition_duration" = "30 DAY"
);

* Priority for Hot Data: StarRocks treats any data within the last 30 days (based on your partition column) as "hot." * Automatic Eviction: If your SSD cache gets full, StarRocks uses an LRU (Least Recently Used) policy to clear space. However, if a user queries data that is within the 30-day window but was evicted, StarRocks will automatically pull it from S3 and re-cache it on the SSD. * Cold Data Stays Cold: If someone queries an alert from 6 months ago, StarRocks will stream it from S3 but will not store it in your SSD cache. This prevents a single "historical search" from wiping out your fast 30-day cache. 2. Physical Setup: SSDs on Compute Nodes To ensure sub-second performance, your Compute Nodes (CNs) need local SSD/NVMe storage. * In your

cn.conf

(or

be.conf

), you point the

storage_root_path

to your SSD mount point. * The parameter

starlet_star_cache_disk_size_percent

(default 80%) tells StarRocks how much of that SSD to use for the cache. 3. Sub-second Querying: Beyond the Cache While the SSD cache provides the fast I/O, StarRocks uses several other features to hit sub-second speeds for full-text search: * Data Cache Warmup: You can "pre-heat" the cache. For example, if you just loaded a batch of new alerts, you can run a

CACHE SELECT

command to pull them into the SSDs before the first user query hits. * Segment-level Metadata: Even for data on S3, StarRocks keeps "Zone Maps" (Min/Max values) in memory. It often knows a file doesn't contain your data without ever looking at the SSD or S3. * Inverted Index + Cache: In v4.1.1, the Inverted Index files themselves are cached. This means the "search" part of your query happens at local-disk speeds, not S3-network speeds. Does it actually hit sub-second? Yes. Benchmarks show that a Shared-data cluster with Data Cache enabled on SSDs typically performs similarly to or even faster than a traditional Shared-nothing (local disk only) cluster. This is because StarRocks can use the cache more granularly (at the block level) than a traditional filesystem. Summary of the Strategy 1. Provision CN nodes with enough NVMe/SSD space to hold roughly 30 days of your "hot" data. 2. Set

"datacache.partition_duration" = "30 DAY"

. 3. Result: Your users get sub-second dashboards for recent alerts, while the "many customers" with years of history only cost you pennies for S3 storage. References • deployment/shared_data/feature-support-shared-data.md • deployment/shared_data/s3.md • administration/management/BE_configuration.md References • deployment/shared_data/s3.md • deployment/shared_data/feature-support-shared-data.md • administration/management/BE_configuration.md References • deployment/shared_data/feature-support-shared-data.md • administration/management/BE_configuration.md

Rocky

07/02/2026, 2:49 PM

• deployment/shared_data/s3.md • deployment/shared_data/azure.md

Eliezer Talker

07/02/2026, 2:54 PM

@Rocky this means the compute nodes are stateful no ? because we keep the last 30 days on ssd disk

Rocky

07/02/2026, 2:55 PM

This is a great architectural question. While the SSDs hold data, the nodes are still considered stateless in the way they are managed and scaled. Here is the technical distinction between why a "Data Cache" doesn't make a node "Stateful" in the traditional sense: 1. Persistence vs. Performance * The "Source of Truth" is S3: In a stateful system (like StarRocks Shared-nothing or traditional databases), if a node's disk dies, the data on it is gone, and you must restore from a replica or backup. * The CN node is a "Disposable Worker": In the Shared-data model, if a Compute Node (CN) is deleted or its SSD fails, zero data is lost. The next time a query needs that data, StarRocks simply pulls it from S3. The SSD is only there for speed, not for integrity. 2. No Data Rebalancing (The "Stateless" Benefit) This is the biggest operational win. * Stateful (Shared-nothing): If you add a new node, the cluster must move terabytes of data from old nodes to the new node to balance the load. This can take hours and saturate your network. * Stateless (Shared-data): If you add 10 new CN nodes, they are ready to work in seconds. They don't need to "rebalance" because they all have equal access to S3. They will naturally build up their own local SSD caches as they process queries. 3. Scaling "In and Out" vs. "Up and Down" Because they are stateless, you can use Auto-scaling (like Kubernetes HPA or AWS Auto Scaling Groups): * Daytime: Spin up 20 CN nodes to handle high search traffic. * Nighttime: Kill 15 of those nodes to save money. * When those 15 nodes die, you don't have to worry about the data they "held." It's all safe on S3. Can you make the cache "sticky"? Even though the nodes are stateless, you can choose to make the cache persistent across restarts to avoid a "cold start" (where the first query after a restart is slow): * On Kubernetes: You can use a Persistent Volume Claim (PVC) for the cache directory. If a CN pod restarts, it re-attaches to the same SSD and finds its 30-day cache already there. * On VMs: Simply don't wipe the SSD mount point on reboot. Summary The compute nodes are architecturally stateless but locally optimized. You get the operational ease of a stateless app (fast scaling, easy upgrades, no rebalancing) with the sub-second performance of a stateful database. References • introduction/Architecture.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache.md References • introduction/Architecture.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache.md • using_starrocks/caching/block_cache.md ) References • quick_start/helm.md • introduction/Architecture.md • using_starrocks/caching/block_cache.md • data_source/data_cache.md

Eliezer Talker

07/02/2026, 3:17 PM

@Rocky so each compute node warms up -> does this mean that if Ingest data then the compute nodes still dont have the last x days ? (same if I add more compute nodes) ?

Rocky

07/02/2026, 3:17 PM

This is an excellent point. You are touching on the "cold start" problem in distributed systems. In StarRocks, there are three specific mechanisms to ensure you don't lose that sub-second performance during ingestion or scaling: 1. Ingestion: "Write-through" Cache When you ingest data into a Shared-data cluster, the compute node (CN) performing the load does two things: * It writes the data to S3 (the permanent store). * It simultaneously writes the data to its local SSD cache. This means the very last "X days" of data are immediately hot on the nodes that handled the ingestion. You don't have to wait for a user to query it first. 2. Adding Compute Nodes: Two Solutions When you add a brand-new compute node, its SSD is indeed empty. StarRocks handles this in two ways: A. Cache Sharing (The "Fast Peer-to-Peer" approach) StarRocks has a feature called Cache Sharing. When a new node joins, it knows which data blocks it is responsible for. If it doesn't have a block locally, it will check if another node in the cluster has it in its SSD. * If a peer node has it, the new node pulls it over the local network (10Gbps/25Gbps) instead of S3. * This is significantly faster than an S3 download and prevents the "S3 bottleneck" when scaling. B. Manual/Scheduled Warmup (
CACHE SELECT
) If you want to ensure a new node (or the whole cluster) is fully primed for the last 30 days, you can use the CACHE SELECT
command. It allows you to "force-warm" specific data:

Copy code

sql
-- Warm up only the last 30 days of data across the cluster
CACHE SELECT * FROM alerts 
WHERE alert_time >= now() - interval 30 day;

You can even automate this as a background task so that any "cold" blocks are filled every hour:

Copy code

sql
SUBMIT TASK warmup_hot_data 
SCHEDULE EVERY (INTERVAL 1 HOUR)
AS 
CACHE SELECT * FROM alerts WHERE alert_time >= now() - interval 30 day;

3. Does it stay "Hot" on all nodes? In StarRocks, data is divided into Tablets. A specific Tablet is usually assigned to one node at a time to maximize cache hits. * If you have 10 nodes, each node "owns" the cache for 1/10th of your data. * When a query comes in, the FE (Frontend) knows exactly which node has the cache for that specific piece of data and routes the query there. Summary * Ingestion: Data is hot immediately (cached during the write). * Scaling: New nodes can pull cache from existing nodes (Cache Sharing) or you can proactively warm them up (

CACHE SELECT

). * Result: You maintain sub-second performance even as you move data in and out of the cluster. References • data_source/block_cache_warmup.md • data_source/data_cache.md • deployment/shared_data/feature-support-shared-data.md • using_starrocks/caching/block_cache.md References • data_source/block_cache_warmup.md • deployment/shared_data/feature-support-shared-data.md

Eliezer Talker

07/02/2026, 3:22 PM

@Rocky then why would we need to do CACHE SELECT
if upon ingestion or adding new compute nodes or having less compute nodes all are right away up to date ?

Rocky

07/02/2026, 3:22 PM

You are right that StarRocks is very efficient at keeping things "warm" automatically, but

CACHE SELECT

exists to handle the edge cases where automation isn't enough to guarantee sub-second performance for that very first user. Here is why you still need

CACHE SELECT

even with "Write-through" caching and auto-scaling: 1. The "First Query" Penalty Even if data is cached during ingestion, it is only cached on the specific Compute Nodes (CNs) that processed that load. * If your ingestion was handled by Node A and Node B, but a later query is distributed across Nodes A, B, C, and D, then Nodes C and D will be "cold." * The first user to run that query will experience a slight delay while C and D pull data from S3. *

CACHE SELECT

allows you to proactively "prime" every node in the cluster so the first human user gets a sub-second response. 2. Recovering from "Cache Eviction" Your SSDs are limited. If a developer accidentally runs a massive query on 2-year-old "cold" data, the LRU (Least Recently Used) policy might decide to evict some of your 30-day "hot" data to make room for that historical query. * Once that historical query is done, your "hot" data is gone from the SSD. * You can use a scheduled

CACHE SELECT

task to "police" your cache and ensure your 30-day window is always put back on the SSDs if it ever gets bumped out. 3. Scaling "Out" (New Nodes) When you add a brand-new Compute Node, its SSD is 100% empty. _ While it _could* wait for queries to naturally fill it up, its performance will be inconsistent (slow at first, then fast). * By running

CACHE SELECT

right after adding nodes, you bring them up to "full speed" before you route production traffic to them. 4. Data Lake / External Tables If you use StarRocks to query data in S3/Iceberg/Hive that was produced by another system (like Spark or Flink), StarRocks didn't "see" the ingestion. * There is no "Write-through" cache for external data. _ In this case,

CACHE SELECT

is the _only* way to get that data onto your SSDs before a user asks for it. 5. Changes in "Hot" Data Definition Imagine your policy is usually 30 days, but it's Black Friday, and you suddenly need the last 90 days to be sub-second for the marketing team. * You change the property to

"30 DAY"

"90 DAY"

. * StarRocks won't automatically download those extra 60 days of old data from S3 just because you changed a setting. * You run

CACHE SELECT ... WHERE date > 90_days_ago

to manually pull that historical data into the "hot" zone. Summary * Automatic Cache: Great for day-to-day "fresh" data. * CACHE SELECT: Great for predictability. It turns "it should be fast" into "I guarantee it is already on the disk." References • data_source/block_cache_warmup.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache.md • using_starrocks/caching/block_cache.md References • administration/management/monitoring/metrics.md • administration/management/monitoring/metrics-shared-data.md

Eliezer Talker

07/02/2026, 3:25 PM

@Rocky when a new compute node comes up you said it automatically takes from other nodes the tablets it needs no ? plus isn't there a way to say never evict my cache becuase of a query to s3 ? like only evict if it expired ?

Rocky

07/02/2026, 3:26 PM

To answer your questions precisely: Yes, there is a "peer-to-peer" mechanism for scaling, and yes, there are ways to protect your cache from being wiped out by large, one-off queries. 1. Does a new node pull from other nodes? Yes, if you enable "Cache Sharing." By default, a new node might pull from S3. However, StarRocks has a feature called Cache Sharing specifically designed for elastic scaling. * How it works: When a new node needs a data block that it doesn't have locally, it checks if any other node in the cluster has it. If found, it pulls the data over the internal network (Peer-to-Peer) instead of S3. * How to enable it:

Copy code

sql
    -- In FE (Global)
    SET GLOBAL enable_trace_historical_node = true;
    -- In Session or Global
    SET enable_datacache_sharing = true;

This prevents the "S3 bottleneck" when you suddenly add 5 or 10 nodes to the cluster. ────────── 2. Can I prevent a "cold query" from evicting my "hot cache"? You are worried that a user might run a "Scan everything from last year" query and kick out your precious "last 30 days" cache. You have two main lines of defense: A. The SLRU Policy (Automatic Protection) StarRocks uses SLRU (Segmented LRU) by default. It divides the cache into two zones: 1. Eviction Segment: Where new data from S3 first lands. 2. Protection Segment: Where frequently accessed "hot" data lives. If a user runs a massive query on old S3 data, that data enters the Eviction segment. It cannot kick data out of the Protection segment unless it is accessed multiple times and "promoted." This protects your 30-day "hot" data from being evicted by one-off historical scans. B. The "Never Populate" Switch (Manual Control) If you are about to run a massive data-mining query or a backup and you want to guarantee it doesn't touch the cache, you can tell StarRocks to bypass the cache for that specific session:

Copy code

sql
-- This query will read from S3 but will NOT save to SSD 
-- and will NOT evict anything currently on the SSD.
SET populate_datacache_mode = 'never';
SELECT count(*) FROM big_table WHERE date < '2023-01-01';

C.
partition_duration
vs. Disk Limit * datacache.partition_duration
: This tells StarRocks which data should be hot (e.g., "1 MONTH"). It helps the system prioritize what to load. * Physical Eviction: Regardless of the timer, if your SSD hits its limit (default 80%), it must evict something to keep the system running. It will use the SLRU logic to pick the "coldest" data to drop. Summary Recommendation To keep your 30-day SSD cache stable: 1. Enable Cache Sharing so new nodes don't hammer S3. 2. Use SLRU (it's the default in newer versions) to segment your cache. 3. Set
populate_datacache_mode = 'never'
for any batch/ETL jobs that scan historical data. References • data_source/data_cache.md • using_starrocks/caching/block_cache.md • sql-reference/System_variable.md • deployment/shared_data/feature-support-shared-data.md References • data_source/data_cache.md • using_starrocks/caching/block_cache.md • data_source/data_cache_troubleshooting.md • using_starrocks/caching/query_cache.md

Eliezer Talker

07/02/2026, 3:30 PM

@Rocky Im confused, 1. I want the following: we say keep the last 30 days in disk thats hot data and if a query comes for data thats not in our hot data then it will get it from s3 but it will not cache it , is that possible ? 2. when a new compute nodes comes , does it take the tablets from other compute nodes when it boots up or only when it gets a query and it sees its disk is empty ?

Rocky

07/02/2026, 3:30 PM

This is definitely possible, and your intuition about how scaling works is mostly correct, but there is a nuance between Tablet Assignment and Data Caching. 1. Caching only the last 30 days Yes, you can strictly enforce a "30-day hot" rule using the table property

datacache.partition_duration

. * How it works: When you set this property, StarRocks checks the partition's time range. If the data belongs to a partition older than 30 days, StarRocks will read it from S3 but will not write it to the local SSD cache. * SQL Command:

Copy code

sql
    ALTER TABLE my_table SET ("datacache.partition_duration" = "30 DAY");

* Result: * Last 30 days: Queries hit SSD (Hot). * Older than 30 days: Queries read from S3 and leave the SSD cache untouched (Cold). This prevents historical "one-off" queries from evicting your valuable hot data. 2. When a new node joins: Boot-up vs. Query-time There are two separate things happening when a new Compute Node (CN) comes online: *A. Tablet Assignment (Metadata) — Happens at Boot/Scaling* The FE (Frontend) immediately sees the new node and starts re-assigning "ownership" of some tablets to it to balance the load. This is purely a metadata operation (the node is told "you are now responsible for Tablet #101"). It happens automatically as soon as the node is healthy. *B. Cache Data (SSD) — Happens at Query-time (Reactive)* By default, the actual data blocks (the cache) are not moved automatically upon boot-up. The new node’s SSD remains empty until one of two things happens: 1. A Query arrives: When a query hits the new node, it realizes its cache is empty. If Cache Sharing is enabled, it will pull the data from a peer node (fast) instead of S3 (slow). 2. You run `CACHE SELECT`: This is the only way to make the data move "proactively" before a user runs a query. Summary of the "Scaling" flow: 1. Node Boots: FE assigns it tablets (Metadata only). 2. Idle State: The node has no data on its SSD yet. 3. First Query: _ _Without Cache Sharing:* Node downloads from S3 (Slow). _ _With Cache Sharing:* Node pulls from a peer's SSD (Fast). _ _With `CACHE SELECT`:* The node was already filled manually (Instant). Why doesn't it move data automatically at boot? Automatically moving terabytes of cache data every time you scale could saturate your internal network and slow down the whole cluster. StarRocks prefers the "lazy" approach (only move what's actually being queried) or the "explicit" approach (

CACHE SELECT

) to give you control over your network bandwidth. References • using_starrocks/caching/block_cache.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache.md • data_source/block_cache_warmup.md References • data_source/block_cache_warmup.md • data_source/data_cache.md • deployment/shared_data/feature-support-shared-data.md • using_starrocks/caching/block_cache.md References • deployment/shared_data/feature-support-shared-data.md • data_source/block_cache_warmup.md

Eliezer Talker

07/02/2026, 3:36 PM

@Rocky can we configure when scale do CACHE SELECT
? and also if we dont but enable data Cache Sharing then when the compute node gets the query does it take long to get the data from a other compute node ?

Rocky

07/02/2026, 3:36 PM

To answer your two specific questions: 1. Can we configure
CACHE SELECT
to trigger automatically upon scaling? There is no native "on-scale-up" trigger inside StarRocks that automatically starts a

CACHE SELECT

the moment a new node joins. However, you can achieve the same result using two common methods: * Method A: Scheduled Warmup (Built-in) Starting in v3.3.0, you can use the

SUBMIT TASK

command to run a warmup periodically. This ensures that even if you don't manually trigger it, the new nodes will be "primed" within a few minutes of coming online.

Copy code

sql
    -- Warm up the hot data window every 5 minutes
    SUBMIT TASK daily_warmup
    SCHEDULE EVERY(INTERVAL 5 MINUTE)
    AS CACHE SELECT * FROM my_table WHERE date >= days_add(now(), -30);

* Method B: Orchestration (External) If you use Kubernetes (StarRocks Operator) or a script to scale your cluster, the best practice is to append a

CACHE SELECT

call to your scaling workflow. Once the new nodes are "Healthy," your script sends the SQL command to the FE to begin the warmup. ────────── 2. Is Data Cache Sharing (Peer-to-Peer) slow? No, it is significantly faster than S3. While local SSD is always the fastest, Cache Sharing is designed to bridge the gap between "Instant SSD" and "Slow S3." Here is how the performance typically breaks down: 1. Local SSD Cache: Sub-millisecond latency. High throughput. 2. Cache Sharing (Peer-to-Peer): Low millisecond latency. Speed is limited only by your internal VPC network (typically 10Gbps to 25Gbps). Since StarRocks nodes are usually in the same availability zone, this transfer is very fast. 3. S3/Object Storage: High latency (often 50ms–100ms+ per request). Throughput can be high but is much more "jittery" than a direct network transfer between nodes. The result: In a 1TB benchmark, queries hitting the Data Cache (even with scaling happening) were roughly 3x faster than queries reading directly from S3. How to monitor it: If you want to see exactly how much time is spent pulling data from "peer" nodes versus S3, you can check the following metrics in your Query Profile: * `DataCacheReadPeerTimer`: Time spent reading from other nodes. * `DataCacheReadPeerBytes`: Total data transferred between nodes. Summary * Automatic scaling warmup: Use

SUBMIT TASK

for a periodic "safety net" or trigger it via your scaling script. * Cache Sharing Speed: It is a massive improvement over S3. It prevents the "performance cliff" users usually fall off when a new node joins. References • data_source/block_cache_warmup.md • data_source/data_cache.md • deployment/shared_data/feature-support-shared-data.md • administration/management/FE_configuration.md References • deployment/shared_data/feature-support-shared-data.md • using_starrocks/caching/block_cache.md • deployment/shared_data/s3.md • knowledge/usage/load/shared_data_batch_ingestion.md

Eliezer Talker

07/02/2026, 3:38 PM

@Rocky Method B: Orchestration (External) If you use Kubernetes (StarRocks Operator) or a script to scale your cluster, the best practice is to append a

CACHE SELECT

call to your scaling workflow. Once the new nodes are "Healthy," your script sends the SQL command to the FE to begin the warmup. -> does it get all the data or only the tablet that it is responsible for ? and does the other node delete those tablets ?

Rocky

07/02/2026, 3:39 PM

References • deployment/shared_data/feature-support-shared-data.md • faq/shared_data_faq.md • data_source/data_cache.md • data_source/data_cache_troubleshooting.md • using_starrocks/caching/block_cache.md

Eliezer Talker

07/02/2026, 3:42 PM

@Rocky i asked does it get all the data or only the tablet that it is responsible for ? and does the other node delete those tablets ? you didnt answer

Rocky

07/02/2026, 3:42 PM

To answer your two specific questions about what happens during scaling and the

CACHE SELECT

process: 1. Does
CACHE SELECT
get all data or only what a node is "responsible" for? It only caches the tablets the node is responsible for. Because

CACHE SELECT

works exactly like a regular query (it is technically an

INSERT INTO BLACKHOLE

), it follows StarRocks' standard distributed execution logic: * The FE (Frontend) looks at the table's tablet distribution and sees which Compute Nodes (CN) are currently responsible for which tablets. * The Tasks are then sent only to the nodes that own those specific tablets. * Result: Each node only pulls and caches the data blocks for the tablets it is assigned. If you have 3 nodes and 300 tablets, and you add a 4th node, once the FE rebalances the tablets (e.g., 75 tablets per node), the new node will only cache the 75 tablets it now "owns" when you run

CACHE SELECT

. 2. Does the "old" node delete those tablets immediately? No, the deletion is "Lazy" (handled by LRU). When a tablet is moved from an old node to a new node during scaling, the old node does not immediately wipe those data blocks from its SSD. * The Reason: StarRocks treats the SSD as a "best-effort" cache. Deleting files every time a tablet moves would create unnecessary disk I/O and CPU overhead. * The Process: The old data blocks simply stay on the old node's disk. Since the FE no longer sends queries for those tablets to the old node, those blocks become "cold" (they aren't being used). * Eviction: Eventually, as the old node caches new data from queries it is responsible for, the LRU (Least Recently Used) policy will identify those old tablet blocks as the oldest and overwrite them to make room for new data. *Why this is actually a benefit: Cache Sharing* Because the old node keeps the data for a while, it allows the Cache Sharing feature to work. 1. A tablet moves from Node A to Node B. 2. Node B (the new node) gets a query for that tablet. Its disk is empty. 3. Instead of going all the way to S3, Node B asks the cluster, "Does anyone have this?" 4. Node A says "Yes, I still have it in my SSD!" and sends it to Node B over the local network. This makes the scaling process much smoother and prevents a "performance cliff" where the system slows down while the new node waits for S3 downloads. Summary * New Node: Only caches the tablets assigned to it. * Old Node: Keeps the old data until its disk fills up and needs to evict it (LRU). * v4.0 Note: A new configuration

lake_enable_drop_tablet_cache

was introduced to allow more aggressive cleanup, but for standard scaling, the lazy LRU approach is the default. References • using_starrocks/caching/block_cache.md • data_source/block_cache_warmup.md • data_source/data_cache.md • administration/management/FE_configuration.md References • data_source/data_cache.md • deployment/shared_data/feature-support-shared-data.md • administration/management/FE_configuration.md • using_starrocks/caching/block_cache.md • faq/shared_data_faq.md • knowledge/admin_and_operation/shared_data_compaction.md

Eliezer Talker

07/02/2026, 3:46 PM

@Rocky how does that work with data becomes cold and need to be transferred to s3, I mean like if the compute node still has it in its SSD and no other compute node got it yet (no one queried that data), or maybe another compute also has this (this data was queried) or maybe another compute node has half of it (there was a partial query for it)

Rocky

07/02/2026, 3:46 PM

In StarRocks' shared-data architecture, the process is simpler than you might expect because S3 (or other object storage) is always the "Source of Truth." Here is how your specific scenarios work: 1. "Data becomes cold and needs to be transferred to S3" There is no transfer from SSD to S3 when data becomes cold. * Write Path: When you load data, StarRocks writes it to S3 immediately (or asynchronously in a short background buffer). At the same time, it places a copy in the Compute Node's (CN) SSD cache. * Cold Data: When data becomes "cold" (not queried for a long time), it is simply deleted (evicted) from the SSD cache to make room for new data. Since the data is already safely in S3, nothing needs to be "sent back" to the cloud. 2. "If only one node has it in SSD and it hasn't been queried elsewhere" If Node A has the data in its SSD and Node B suddenly needs it: * Cache Sharing: Node B will first check if any other node in the cluster has those data blocks. * The Fetch: Node B will pull the data directly from Node A's SSD over the internal network. This is much faster than Node B downloading it from S3. * Result: Now both nodes have a copy in their SSDs. 3. "If another compute node has half of it (partial query)" StarRocks Data Cache (v3.2+) works in small blocks (typically 1MB to multiples of MBs), not entire files. * If a query only needs the "first half" of a file, only those specific blocks are cached. * If Node B then needs the "second half," it will see that no one in the cluster has the second half. It will download only that missing portion from S3 and cache it locally. * Result: Node A has the first half, Node B has the second half. If a future query needs the whole thing, the nodes will share their respective halves with each other. 4. "What if the Compute Node crashes before it sends data to S3?" If you use the default Synchronous Ingestion, the load command won't return "Success" until the data is safely in S3. If you use Asynchronous Ingestion (to speed up loads): * Data is temporarily stored in a local "spill" or "staging" area on the CN. _ If the CN crashes _before* it finishes the upload to S3, that specific load job will fail, and you will need to retry it. StarRocks ensures that you never have "phantom" data that exists only on a local disk but is considered "committed" to the database. Summary * S3 is the parent: Data is never "moved" to S3; it's born there. * SSD is the shortcut: The SSD is just a local copy used for speed. * Block-level sharing: Nodes are smart enough to pull only the specific 1MB blocks they need from each other, even if they only have pieces of the data. References • introduction/Architecture.md • deployment/shared_data/s3.md • using_starrocks/caching/block_cache.md • deployment/shared_data/feature-support-shared-data.md References • administration/management/FE_configuration.md • deployment/shared_data/s3.md • deployment/shared_data/feature-support-shared-data.md • administration/management/BE_configuration.md • using_starrocks/caching/block_cache.md • faq/shared_data_faq.md

Rocky

07/02/2026, 3:46 PM

To clarify how this works in StarRocks' shared-data (cloud-native) architecture, it's important to understand that the SSD cache and S3 storage are decoupled. 1. Data is never "transferred" to S3 when it becomes cold In a shared-data cluster, S3 is the primary storage. * Write Path: When you load data, it is written to S3 and the local SSD cache simultaneously. * Cold Data: When data becomes "cold" (not queried for a long time) and the SSD fills up, StarRocks simply deletes (evicts) the data from the SSD. It does not need to "transfer" it to S3 because a copy is already there. * Re-warming: If you query that cold data later, the node will fetch it from S3 and put it back into the SSD cache. 2. Scenario: Data is only on one node's SSD (and no one else has queried it) If Node A has data in its SSD that Node B suddenly needs (perhaps because of a scaling rebalance), StarRocks uses Cache Sharing: * The Check: Before going to S3, Node B asks the cluster if anyone has those specific data blocks. * The Transfer: Node A will send the data blocks to Node B over the local network. * Efficiency: This is significantly faster than Node B downloading the data from S3. Once Node B has it, it stores it in its own SSD. 3. Scenario: Another node has "half" of the data (Partial Cache) StarRocks' Data Cache does not work on whole files; it works on Blocks (typically 1MB each). * If a query only scanned the "first half" of a 100MB file, only those 50 blocks are in the cache. * If a new query needs the "second half," the node will see those blocks are missing. It will download only the missing 50 blocks from S3. * Result: The cache is granular. You can have a "Swiss cheese" cache where only the specific parts of a table that are frequently queried are kept on SSD, while the rest stays on S3. 4. Is there ever a risk of losing data? No. Because S3 is the "Source of Truth," the SSD is treated as disposable. * If a Compute Node (CN) crashes, no data is lost. The system simply spins up a new node, which starts with an empty SSD and begins pulling data from S3 (or other nodes) as needed. * The only exception is Asynchronous Ingestion (a performance setting). If enabled, data is buffered locally before being sent to S3. If a node crashes during that few-second window, that specific load job fails, and you must re-run the load. Summary Scenario | Behavior Data becomes cold | Evicted (deleted) from SSD. S3 copy remains untouched. Node A has it, Node B needs it | Node B pulls it from Node A's SSD (Cache Sharing). Only part of data is queried | Only those specific 1MB blocks are cached. Scaling/Rebalancing | New node pulls blocks from old nodes or S3; old node eventually evicts them via LRU. References • introduction/Architecture.md • using_starrocks/caching/block_cache.md • data_source/data_cache.md • deployment/shared_data/s3.md References • deployment/shared_data/s3.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache.md

Eliezer Talker

07/02/2026, 3:55 PM

@Rocky another question regarding the full text search. you said before something like "

Copy code

sql
    CREATE TABLE search_table (
        id BIGINT,
        json_data STRING,
        -- Indexing the JSON string for full-text search
        INDEX idx_fts (json_data) USING GIN("parser" = "english", "imp_lib" = "builtin")
    )
    DISTRIBUTED BY HASH(id);

" what do you mean by

Copy code

parser" = "english"

? in our use case lets say the user want to search and inputs the text , if our alerts for that tenant are in Chinese a another tenant is Japanese and another tenant is English what does this mean for me ?

Rocky

07/02/2026, 3:57 PM

The

parser

parameter determines how StarRocks breaks a long string of text into individual "tokens" (words) to build the index. Think of it as the "logic" used to decide where one word ends and another begins. For your multi-tenant, multi-language (English, Chinese, Japanese) use case, here is what that means for you: 1. What "english" means If you use

"parser" = "english"

, the indexer only looks for non-alphabetic characters (like spaces, commas, or periods) to separate words. * The Problem: Chinese and Japanese do not use spaces between words. * The Result: An English parser would treat an entire Chinese sentence as one single giant word. If a user searches for a specific 2-character word inside that sentence, the index won't find it because it didn't "break" the sentence correctly. 2. The Solution for your Multi-language case Since you have a mix of English, Chinese, and Japanese in the same column, you should not use the

english

parser. Instead, use: Recommended:
"parser" = "standard"
The

standard

parser is designed for multilingual data. * How it works: It uses the Unicode Text Segmentation algorithm. It is smart enough to distinguish between English (using spaces) and CJK (Chinese, Japanese, Korean) characters. * Why for you: It will correctly tokenize English "Alert" into

alert

and also handle the lack of spaces in Chinese/Japanese text. It is the best "catch-all" for a multi-tenant system. Alternative:
"parser" = "chinese"
* How it works: It uses a specific CJK Analyzer (Chinese-Japanese-Korean). * Why for you: If your data is overwhelmingly Asian languages, this is very effective. It is specifically tuned to find word boundaries in scripts that don't use spaces. 3. Summary of Options Parser | Best for... | Behavior with Chinese/Japanese

english

| Pure English | Bad. Treats whole sentences as one word.

chinese

| Chinese, Japanese, Korean | Good. Uses CJK-specific word breaking.

standard

| Mixed languages | Best. Handles English and CJK in the same column. What this means for your Code You should change your table definition to use the

standard

parser so that all your tenants' alerts are searchable regardless of their language:

Copy code

sql
CREATE TABLE search_table (
    id BIGINT,
    tenant_id INT,
    json_data STRING,
    -- Using 'standard' to support English, Chinese, and Japanese together
    INDEX idx_fts (json_data) USING GIN("parser" = "standard")
)
DISTRIBUTED BY HASH(id);

Note: When searching, StarRocks uses the

MATCH

keyword. Because the

standard

parser also converts English to lowercase, ensure your search queries for English terms are also lowercase. References • table_design/indexes/inverted_index.md • administration/management/FE_configuration.md • using_starrocks/caching/block_cache.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache.md References • table_design/indexes/inverted_index.md

Rocky

07/02/2026, 3:59 PM

The

parser

parameter determines how StarRocks breaks down your text into individual "searchable" words (tokens). In a multi-tenant scenario with English, Chinese, and Japanese, choosing the right parser is critical because these languages use very different rules for word boundaries. Here is the breakdown of what those values mean and which one fits your case: 1. The Parsers Explained * "english"
: * How it works: It splits text at any non-alphabetic character (spaces, commas, periods) and converts everything to lowercase. * Problem for you: It will fail on Chinese and Japanese because those languages often do not use spaces between words. It would treat a whole Chinese sentence as one giant, unsearchable block. * "chinese"
: * How it works: It uses the CJK Analyzer (Chinese, Japanese, Korean). * Benefit: Even though it’s named "chinese," it is specifically designed to handle the logographic nature of all three CJK languages by using "bi-gram" tokenization (splitting text into overlapping pairs of characters). * "standard"
(Recommended for you): * How it works: This is a multilingual parser based on the Unicode Text Segmentation algorithm. * Why it fits your case: It is designed to distinguish between different scripts. It can handle English (using space-based rules) and Chinese/Japanese (using script-based rules) in the same column. 2. Recommendation for Multi-Tenant (English/Chinese/Japanese) Since you have different tenants using different languages in the same table, you should use the standard
parser.

Copy code

sql
INDEX idx_fts (json_data) USING GIN("parser" = "standard")

Why
standard
? * Tenant A (English): It will split "Alert: Server Down" into

alert

server

down

. * Tenant B (Chinese): It will correctly identify Chinese character boundaries even without spaces. * Tenant C (Japanese): It handles Japanese Kanji and Kana using Unicode rules. 3. How to Search Once you use the

standard

parser, you must use the

MATCH

syntax to search. StarRocks will automatically apply the same "standard" rules to the user's input.

Copy code

sql
-- This works for any language if the index is set to "standard"
SELECT * FROM search_table 
WHERE json_data MATCH '服务器'; -- Chinese for 'Server'

Summary of Differences Parser | Best For | Multi-Language Support

english

| Pure English logs/text. | Poor (fails on CJK).

chinese

| Pure Chinese, Japanese, or Korean. | Good for CJK, okay for English.

standard

| Mixed environments or multi-tenant. | Best (Unicode-aware). Important Note: Full-text search (GIN index) in StarRocks is currently an experimental feature. You must enable it globally before creating the table:

Copy code

sql
ADMIN SET FRONTEND CONFIG ("enable_experimental_gin" = "true");

References • table_design/indexes/inverted_index.md References • table_design/indexes/inverted_index.md • sql-reference/sql-statements/data-definition/CREATE_INDEX.md • sql-reference/sql-statements/data-definition/ALTER_TABLE.md • administration/management/FE_configuration.md • faq/loading_faq.md • using_starrocks/caching/block_cache.md • sql-reference/sql-statements/data-definition/CREATE_TABLE.md • table_design/indexes/inverted_index.md

Rocky

07/02/2026, 3:59 PM

Rocky

07/02/2026, 3:59 PM

Rocky

07/02/2026, 3:59 PM

Rocky

07/02/2026, 3:59 PM

Rocky

07/02/2026, 3:59 PM

Rocky

07/02/2026, 3:59 PM

Rocky

07/02/2026, 3:59 PM

Rocky

07/02/2026, 3:59 PM

Rocky

07/02/2026, 3:59 PM

Eliezer Talker

07/02/2026, 7:46 PM

@Rocky in the last comment you said "*Important Note:* Full-text search (GIN index) in StarRocks is currently an experimental feature. You must enable it globally before creating the table:" -> so does this mean its not production ready ? should I not use it for production ? when did this feature come out ? im using starRocks version 4.1.1 also how would the english/standard parser tokenize this: "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" or this: "176.229.220.64"

Rocky

07/02/2026, 7:51 PM

Since you are on StarRocks v4.1.1, you are using the most current version (released in mid-2026). Here is the breakdown of the feature status and the tokenization behavior you asked about. 1. Is it Production Ready? The "Experimental" label can be confusing. In StarRocks 4.1.1, the Full-text Inverted Index (GIN) is officially supported and is a core part of the "Built for Production" release. * Status: It is technically in Beta. In StarRocks terms, "Beta" means the feature is functional and production-ready for most users, but the "Experimental" flag (

enable_experimental_gin

) is kept to ensure users are aware they are using a newer indexing engine. * Version History: It first appeared in v3.3 (CLucene-based). In v4.1, StarRocks introduced a completely new Native Built-in Inverted Index engine that is significantly faster and supports both shared-nothing and shared-data (S3) architectures. * Recommendation: Yes, you can use it in production. The StarRocks engineering team specifically optimized the 4.1 release to handle high-concurrency "log-style" searching at scale. ────────── 2. Tokenization Examples The way text is broken down determines what your users can actually "search" for. Example A: File Path

"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe"

Parser | Resulting Tokens (Searchable Keywords) | Reason english
|

windows

system

windowspowershell

powershell

exe

| It splits at any non-alphabetic character. This means

, and numbers (

1.0

) are treated as separators and discarded. You cannot search for "32" or "1.0". standard
|

windows

system32

windowspowershell

v1

powershell

exe

| It follows Unicode TR29 rules. It recognizes that numbers and letters can belong to the same word. It keeps

system32

intact and splits

v1.0

into

v1

and

. Example B: IP Address

"176.229.220.64"

Parser | Resulting Tokens | Reason english
| (Empty) | Since every character is a number or a dot (both non-alphabetic), the parser treats the entire string as one big separator. The IP is effectively invisible to the index. standard
|

| It treats the segments as numeric tokens. A user searching for

MATCH '220'

would successfully find this row. Summary Recommendation For your use case (which includes multi-lingual tenants, paths, and IPs), do not use the
english
parser. It is too restrictive because it ignores numbers. Use the standard
parser. It is the most robust choice for: 1. Mixed Languages: Handling English, Chinese, and Japanese in one column. 2. System Logs: Keeping numbers like

system32

or version numbers searchable. 3. Network Data: Keeping IP segments searchable. SQL for your version (4.1.1):

Copy code

sql
-- Use the native 'builtin' library for best performance on v4.1+
INDEX idx_fts (json_data) USING GIN("parser" = "standard", "imp_lib" = "builtin")

References • table_design/indexes/inverted_index.md • sql-reference/sql-functions/string-functions/tokenize.md • release_notes/release_4.1.md References • table_design/indexes/inverted_index.md • sql-reference/System_variable.md • release_notes/release_3.3.md • table_design/indexes/Index_Overview.md • sql-reference/sql-functions/string-functions/match.md

Rocky

07/02/2026, 7:51 PM

Rocky

07/02/2026, 7:51 PM

Rocky

07/02/2026, 7:51 PM

Rocky

07/02/2026, 7:51 PM

Rocky

07/02/2026, 7:51 PM

Rocky

07/02/2026, 7:51 PM

Rocky

07/02/2026, 7:51 PM

Rocky

07/02/2026, 7:51 PM

Rocky

07/02/2026, 7:51 PM

Eliezer Talker

07/02/2026, 8:09 PM

@Rocky what if I need also the ability for sub string search does version 4.1.1 offer something like that ? is it does is it experimental ?

Rocky

07/02/2026, 8:14 PM

Yes, version 4.1.1 offers exactly what you need for substring search. In fact, StarRocks 4.1 introduced a major enhancement specifically for this called the N-gram Dictionary Index, which is part of the "Built-in" Inverted Index engine. 1. How it works: Substring Search By default, an inverted index is designed to find whole words (tokens). If you search for

%rock%

, a standard index would have to scan its entire dictionary to find every word containing "rock" (like "starrocks", "rocksdb", "bedrock"), which is slow if you have millions of unique words. In v4.1.1, you can use the dict_gram_num
parameter. It breaks down the internal dictionary into even smaller pieces (n-grams) to make substring lookups nearly instant. 2. SQL Example for Substring Search To enable substring acceleration for your multi-lingual/log data, you should use the

builtin

library and set

dict_gram_num

(usually

is best).

Copy code

sql
CREATE TABLE search_table (
    id BIGINT,
    json_data STRING,
    INDEX idx_substring (json_data) USING GIN(
        "parser" = "standard",     -- Best for mixed English/Chinese/Japanese
        "imp_lib" = "builtin",     -- Required for n-gram acceleration
        "dict_gram_num" = "3"      -- Enables substring search for patterns of 3+ chars
    )
) 
DISTRIBUTED BY HASH(id);

How to query it: You can now use wildcards inside the

MATCH

predicate:

Copy code

sql
-- This will find "starrocks", "rocksdb", "bedrock" etc. very quickly
SELECT * FROM search_table WHERE json_data MATCH '%rock%';

3. Is it experimental? Here is the status for version 4.1.1: * Feature Status: It is officially labeled as Beta. * Production Readiness: In StarRocks' lifecycle, Beta means it is feature-complete and tested for performance, but the engineering team keeps the

enable_experimental_gin

flag to ensure users are aware it is a newer engine compared to the classic storage engine. * Recommendation: Many users run GIN indexes in production for log analysis. However, because it is Beta, you should test the storage overhead on your specific data, as n-gram indexes (

dict_gram_num

) can increase the size of the index files on S3/SSD. Summary of Benefits for You: 1. Substring Match: You can find

system32

by searching for

%tem32%

. 2. Shared-Data Ready: The

builtin

implementation is specifically designed to work with your S3 architecture. 3. Language Agnostic: Because it uses n-grams at the dictionary level, it provides a "fuzzy" search capability that works across Chinese, Japanese, and English scripts simultaneously. References • table_design/indexes/inverted_index.md • release_notes/release_4.1.md References • table_design/indexes/inverted_index.md • sql-reference/sql-functions/string-functions/match.md • release_notes/release_3.4.md • table_design/indexes/Index_Overview.md • administration/management/FE_configuration.md • sql-reference/sql-statements/data-definition/CREATE_INDEX.md • sql-reference/sql-statements/data-definition/CREATE_TABLE.md • introduction/maturity.md • sql-reference/System_variable.md

Rocky

07/02/2026, 8:14 PM

Rocky

07/02/2026, 8:14 PM

Rocky

07/02/2026, 8:14 PM

Rocky

07/02/2026, 8:14 PM

Rocky

07/02/2026, 8:14 PM

Rocky

07/02/2026, 8:14 PM

Rocky

07/02/2026, 8:14 PM

Rocky

07/02/2026, 8:14 PM

Rocky

07/02/2026, 8:14 PM

Eliezer Talker

07/02/2026, 8:38 PM

@Rocky inverted indexs, inverted indexs with n-gram, or normal n-gram in your docs say its beta and beta is not recommended for production use. when will it be out of beta you think ?

Rocky

07/02/2026, 8:39 PM

The transition of a feature from "Beta" to "GA" (General Availability) in StarRocks typically happens when the engineering team is confident that the performance, metadata stability, and edge-case handling are robust enough for mission-critical deployments without any manual intervention (like enabling experimental flags). Based on the roadmap and current development trends for version 4.1.x, here is the outlook for the Full-text Inverted Index (GIN): 1. Expected Timeline for GA While there is no fixed date, we can look at the typical StarRocks release cycle: * StarRocks v4.1 (Released Mid-2026): Introduced the Native Built-in Inverted Index. This was a massive architectural shift from the old CLucene library to a native bitmap-based implementation that supports Shared-Data (S3) clusters. * The "Two-Release" Rule: Usually, StarRocks keeps major new features in Beta for at least 2 minor versions to collect feedback from community users. * Projected GA: It is highly likely that the Inverted Index and N-gram dictionary acceleration will move to GA in v4.2 or v4.3 (roughly late 2026 or early 2027). 2. Why is it still "Beta" in v4.1.1? The feature is very stable for searching, but the "Beta" label remains for a few specific reasons: * Storage Overhead: The N-gram dictionary index (

dict_gram_num

) can significantly increase index size on disk. The team is still optimizing the compression ratios for these n-grams. * Metadata Evolution: In Shared-Data architectures (using S3), managing the lifecycle of index files during background compaction is complex. V4.1 was the first version to fully support this on cloud-native storage. * Experimental Flag: The flag

enable_experimental_gin

is kept mainly as a "safety switch" to ensure users check their disk capacity before creating massive indexes. 3. Should you use it in Production now? Yes, with a Proof of Concept (POC). Many StarRocks users in the community are already running GIN indexes in production for log analysis (Elasticsearch-replacement style use cases). Since you are on v4.1.1, you are using the new native engine which is much more reliable than the older v3.3 versions. Rocky's Advice for your 4.1.1 Production deployment: 1. Monitor Storage: Before rolling out to all tenants, create an index for one tenant and check the

du

(disk usage) of your data folder. N-gram indexes can sometimes double the storage size of a column. 2. Use the
builtin
library: Always specify

"imp_lib" = "builtin"

in your

CREATE INDEX

statement. This is the future-proof version designed for v4.1+. 3. Validate on v4.1.1: Since v4.1.1 is the latest patch, many of the initial Beta bugs from 4.1.0 have already been resolved. Summary If you need substring and multilingual search today, the v4.1.1 implementation is the best version to date. You don't necessarily need to wait for the official GA label if your POC shows that the query speed meets your needs and the storage cost is acceptable. References • table_design/indexes/inverted_index.md • release_notes/release_4.1.md • introduction/maturity.md References • table_design/indexes/inverted_index.md

2 Views

Open in Slack

Previous Next