Skip to content

Commit f0a4f7b

Browse files
yingjunwuclaude
yingjunwu
and
claude
authored
docs: SEO & AEO optimization across 23 core pages (#1074)
* docs: SEO & AEO optimization across 23 core documentation pages - Rewrite FAQ pages with H2 question headings (replacing Accordion-only format) and inject FAQPage JSON-LD structured data for Google Rich Snippets - Optimize title and meta description frontmatter across 20+ high-traffic pages with target keywords (streaming database, PostgreSQL-compatible, real-time, etc.) - Add descriptive alt attributes to images for accessibility and image SEO - Rewrite opening paragraphs to be self-contained answers for AEO (Answer Engine Optimization) — enabling AI search engines to cite directly - Improve internal cross-linking with descriptive anchor text - Convert nested Accordion content to structured Markdown with tables and headers Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: address review feedback — fix broken links, trim titles, refine content - Fix 2 broken links: /operate/memory-control → /operate/tune-reserved-memory, /iceberg/iceberg-table-engine → /iceberg/internal-iceberg-tables - Trim 9 titles that exceeded Google's ~60 char SERP display limit - Trim 4 descriptions that exceeded ~160 chars - Remove unverified "sub-20ms p99" performance claim from intro - Soften "20+" and "30+" connector count claims - Shorten dense opening paragraphs in intro.mdx and architecture.mdx - Fix "semi, anti" join terminology per Copilot review - Align "Iceberg table engine" terminology with existing docs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 2a0fca7 commit f0a4f7b

23 files changed

+320
-166
lines changed

‎delivery/overview.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "Overview of data delivery"
3-
description: "RisingWave supports delivering data to downstream systems via its sink connectors."
2+
title: "Data delivery & sink connectors | Export data from RisingWave"
43
sidebarTitle: Overview
4+
description: "Deliver streaming results from RisingWave to downstream systems including Kafka, Iceberg, PostgreSQL, Snowflake, ClickHouse, and S3 via sink connectors."
55
---
66

77
<Tip>

‎deploy/deployment-modes-overview.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
2-
title: "Overview"
3-
description: "Choose the right deployment option for your needs. Compare deployment time, production readiness, and recommended use cases."
2+
title: "Deploy RisingWave | Deployment options"
3+
sidebarTitle: "Overview"
4+
description: "Choose a RisingWave deployment mode: standalone, Docker Compose, Kubernetes/Helm for production, or fully managed RisingWave Cloud."
45
---
56

67
RisingWave supports multiple deployment modes, each designed for different use cases and environments. This guide helps you choose the right option quickly.

‎faq/faq-overview.mdx‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,26 @@
11
---
2-
title: "Frequently asked questions"
2+
title: "RisingWave FAQ | Frequently asked questions"
33
sidebarTitle: "Overview"
4-
description: "Answers to frequently asked questions about RisingWave, including usage, comparisons, and best practices."
4+
description: "Frequently asked questions about RisingWave: when to use it, comparisons with Flink and OLAP databases, memory management, and performance."
55
---
66

7-
This section answers frequently asked questions about RisingWave.
7+
Find answers to commonly asked questions about RisingWave, the PostgreSQL-compatible streaming database for real-time data processing.
88

99
<Columns cols={2}>
10-
<Card
11-
title="Using RisingWave"
12-
icon="gears"
13-
href="/faq/faq-using-risingwave"
14-
>
15-
Find answers to common questions about how RisingWave works, including memory management and query performance.
16-
</Card>
1710
<Card
1811
title="When to use RisingWave"
1912
icon="lightbulb"
2013
href="/faq/faq-when-to-use-risingwave"
2114
>
22-
Understand the ideal use cases for RisingWave and how it compares to other data processing systems like Flink, Spark, and real-time OLAP databases.
15+
Learn when RisingWave is the right choice — including comparisons with Apache Flink, ksqlDB, and OLAP databases like ClickHouse.
16+
</Card>
17+
<Card
18+
title="Using RisingWave"
19+
icon="gears"
20+
href="/faq/faq-using-risingwave"
21+
>
22+
Get answers about memory management, CREATE MATERIALIZED VIEW performance, reserved memory configuration, and resource usage.
2323
</Card>
2424
</Columns>
2525

26-
If you can't find an answer here, please ask in the [#ask-ai channel](https://risingwave-community.slack.com/archives/C06R8DA3DGT) of our [Community Slack](https://www.risingwave.com/slack). Our AI assistant there provides answers based on RisingWave's documentation, codebase, and community discussions.
26+
Can't find what you're looking for? Ask in the [#ask-ai channel](https://risingwave-community.slack.com/archives/C06R8DA3DGT) of our [Community Slack](https://www.risingwave.com/slack). Our AI assistant provides answers based on RisingWave's documentation, codebase, and community discussions.

‎faq/faq-using-risingwave.mdx‎

Lines changed: 119 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,98 @@
11
---
2-
title: "Using RisingWave"
2+
title: "Using RisingWave | Memory, performance & troubleshooting FAQ"
3+
sidebarTitle: "Using RisingWave"
4+
description: "Answers to frequently asked questions about using the RisingWave streaming database, including memory management, reserved memory configuration, CREATE MATERIALIZED VIEW performance, and resource usage breakdown."
35
mode: wide
46
---
57

6-
<AccordionGroup>
7-
<Accordion title="Why the memory usage is so high?">
8-
Don't worry, this is by design. RisingWave uses memory for in-memory cache of streaming queries, such as data structures like hash tables, etc., to optimize streaming computation performance. By default, RisingWave will utilize all available memory (unless specifically configured through `RW_TOTAL_MEMORY_BYTES`/`--total-memory-bytes`). This is why setting memory limits is required in Kubernetes/Docker deployments.
8+
This page answers common operational questions about running RisingWave in production, including memory management, materialized view creation performance, and resource usage.
99

10-
During the instance running, RisingWave will keep memory usage below this limit. If you encounter unexpected issues like OOM (Out-of-memory), please refer to [Troubleshoot out-of-memory](/troubleshoot/troubleshoot-oom) for assistance.
11-
</Accordion>
12-
<Accordion title="Why is the memory for a Serving or Streaming Node not fully utilized?">
13-
As part of its design, RisingWave allocates part of the total memory in the Serving or Streaming Node as reserved memory. This reserved memory is specifically set aside for system usage, such as the stack and code segment of processes, allocation overhead, and network buffer.
10+
## Why is the memory usage so high?
1411

15-
As for the calculation method of reserved memory, starting from version 1.10, RisingWave calculates the reserved memory based on the following gradient:
12+
This is by design. RisingWave uses memory for in-memory caching of streaming query state — data structures like hash tables, aggregation buffers, and join state — to optimize streaming computation performance.
1613

17-
* 30% of the first 16GB
18-
* Plus 20% of the remaining memory
19-
<Accordion title="Details">
20-
Read an example.For example, let's consider a Streaming Node with 32GB of memory. The reserved memory would be calculated as follows:
21-
* 30% of the first 16GB is 4.8GB
22-
* 20% of the remaining 16GB is 3.2GB
23-
* The total reserved memory is 4.8GB + 3.2GB = 8GB
14+
By default, RisingWave utilizes all available memory unless specifically configured through `RW_TOTAL_MEMORY_BYTES` or `--total-memory-bytes`. This is why **setting memory limits is required** in Kubernetes and Docker deployments.
2415

25-
This calculation method ensures that in scenarios with less memory, the system reserves more memory for critical tasks. On the other hand, in scenarios with more memory, it reserves less memory, thus achieving a better balance between system performance and memory utilization.
26-
</Accordion>
16+
During operation, RisingWave keeps memory usage below the configured limit. If you encounter unexpected out-of-memory (OOM) issues, see [Troubleshoot out-of-memory](/troubleshoot/troubleshoot-oom).
2717

28-
However, this may not be suitable for all workloads and machine setups. To address this, we introduce a new option, which allows you to explicitly configure the amount of reserved memory for a Serving or Streaming Node. You can use the startup option `--reserved-memory-bytes` and the environment variable `RW_RESERVED_MEMORY_BYTES` to override the reserved memory configuration for Serving or Streaming Nodes. **Note that the memory reserved should be at least 512MB.**
18+
## Why is the memory for a Serving or Streaming Node not fully utilized?
2919

30-
<Accordion title="Details">
31-
Read an example.For instance, suppose you are deploying a Streaming Node on a machine or pod with 64GB of memory. By default, the reserved memory would be calculated as follows:
32-
* 30% of the first 16GB is 4.8GB
33-
* 20% of the remaining 48GB (64GB - 16GB) is 9.6GB
34-
* The total reserved memory would be 4.8GB + 9.6GB, which equals 14.4GB.
20+
RisingWave allocates a portion of total memory as **reserved memory** for system usage, including the process stack, code segments, allocation overhead, and network buffers.
3521

36-
However, if you find this excessive for your specific use case, you have the option to specify a different value. You can set either `RW_RESERVED_MEMORY_BYTES=8589934592` or `--reserved-memory-bytes=8589934592` when starting up the Streaming Node. This will allocate 8GB as the reserved memory instead.
37-
</Accordion>
22+
### Reserved memory calculation (v1.10+)
3823

39-
<Accordion title="Confused about the version difference of reserved memory setting?">
40-
Before version 1.9, RisingWave allocated 30% of the total memory as reserved memory by default. However, through practical application, we realized that this default setting may not be suitable for all scenarios. Therefore, in version 1.9, we introduced the ability to customize the reserved memory.
24+
Starting from version 1.10, RisingWave calculates reserved memory using a gradient formula:
4125

42-
To further optimize this feature, we changed the calculation method for reserved memory in version 1.10 and introduced the current gradient calculation method. These changes improve memory utilization and provide enhanced performance for our users.
26+
- **30%** of the first 16 GB
27+
- **20%** of the remaining memory
4328

44-
By continuously improving the reserved memory feature, we strive to offer a more flexible and efficient memory management solution to meet the diverse needs of our users.
45-
</Accordion>
46-
</Accordion>
47-
<Accordion title="Why does the `CREATE MATERIALIZED VIEW` statement take a long time to execute?">
48-
The execution time for the `CREATE MATERIALIZED VIEW` statement can vary based on several factors. Here are two common reasons:
29+
**Example**: For a Streaming Node with 32 GB of total memory:
30+
- 30% of the first 16 GB = 4.8 GB
31+
- 20% of the remaining 16 GB = 3.2 GB
32+
- **Total reserved memory = 8 GB**
4933

50-
1. **Backfilling of historical data**: RisingWave ensures consistent snapshots across materialized views (MVs). So when a new MV is created, it backfills all historical data from the upstream MV or tables and calculate them, which takes some time. And the created DDL statement will only end when the backfill ends. You can run `SHOW JOBS;` in SQL to check the DDL progress. If you want the create statement to not wait for the process to finish and not block the session, you can execute `SET BACKGROUND_DDL=true;` before running the `CREATE MATERIALIZED VIEW` statement. See details in [SET BACKGROUND\_DDL](/sql/commands/sql-set-background-ddl). But please notice that the newly created MV is still invisible in the catalog until the end of backfill when `BACKGROUND_DDL=true`.
51-
2. **High cluster latency**: If the cluster experiences high latency, it may take longer to apply changes to the streaming graph. If the `Progress` in the `SHOW JOBS;` result stays at 0.0%, high latency could be the cause. See details in [Troubleshoot high latency](/performance/troubleshoot-high-latency)
52-
</Accordion>
53-
<Accordion title="What consists of the memory usage and disk usage?">
54-
Memory usage is divided into the following components:
34+
This gradient approach ensures more memory is reserved on smaller instances (where system overhead is proportionally larger) while leaving more memory available for computation on larger instances.
5535

56-
* Total memory: The overall available memory for the Serving or Streaming Node.
57-
* Storage memory: Memory dedicated to storage-related tasks, which includes caching data and metadata to improve performance.
58-
* Compute memory: Memory allocated for computational tasks.
59-
* Reserved memory: Memory reserved for system usage, such as the stack and code segment of processes, allocation overhead, and network buffer.
36+
### Custom reserved memory configuration
6037

61-
Below is a specific example of memory usage composition on a Streaming Node with 8G memory:
38+
You can override the default calculation using:
39+
- **Environment variable**: `RW_RESERVED_MEMORY_BYTES=8589934592` (8 GB)
40+
- **Startup option**: `--reserved-memory-bytes=8589934592`
6241

63-
```bash
42+
<Note>
43+
The reserved memory must be at least 512 MB.
44+
</Note>
45+
46+
**Example**: On a 64 GB Streaming Node, the default reserved memory would be 14.4 GB (30% of 16 GB + 20% of 48 GB). If this is excessive for your workload, set `RW_RESERVED_MEMORY_BYTES=8589934592` to allocate only 8 GB.
47+
48+
### Version history of reserved memory
49+
50+
| Version | Behavior |
51+
|---|---|
52+
| Before v1.9 | Fixed 30% of total memory as reserved |
53+
| v1.9 | Introduced customizable reserved memory (`--reserved-memory-bytes`) |
54+
| v1.10+ | Changed to gradient calculation (30% of first 16 GB + 20% of rest) |
55+
56+
## Why does CREATE MATERIALIZED VIEW take a long time?
57+
58+
The execution time for `CREATE MATERIALIZED VIEW` depends on two main factors:
59+
60+
### 1. Backfilling historical data
61+
62+
When a new materialized view is created, RisingWave **backfills all historical data** from the referenced tables and materialized views to ensure a consistent snapshot. The `CREATE` statement blocks until backfilling completes.
63+
64+
**How to check progress**:
65+
```sql
66+
SHOW JOBS;
67+
```
68+
69+
**How to run in background** (non-blocking):
70+
```sql
71+
SET BACKGROUND_DDL = true;
72+
CREATE MATERIALIZED VIEW my_mv AS SELECT ...;
73+
```
74+
75+
<Note>
76+
When `BACKGROUND_DDL=true`, the new materialized view remains invisible in the catalog until backfilling completes. See [SET BACKGROUND_DDL](/sql/commands/sql-set-background-ddl) for details.
77+
</Note>
78+
79+
### 2. High cluster latency
80+
81+
If the `Progress` column in `SHOW JOBS` stays at `0.0%`, the cluster may be experiencing high latency that slows down streaming graph changes. See [Troubleshoot high latency](/performance/troubleshoot-high-latency) for diagnostic steps.
82+
83+
## What does the memory and disk usage consist of?
84+
85+
RisingWave memory usage on a Serving or Streaming Node is divided into three components:
86+
87+
| Component | Description |
88+
|---|---|
89+
| **Storage memory** | Caching data blocks, metadata, and shared buffers to improve read/write performance |
90+
| **Compute memory** | Memory allocated for streaming computation and ad-hoc query execution |
91+
| **Reserved memory** | System overhead: process stack, code segments, allocation, and network buffers |
92+
93+
**Example breakdown** for a Streaming Node with 8 GB total memory:
94+
95+
```
6496
total_memory: 8.00 GiB
6597
storage_memory: 2.13 GiB
6698
block_cache_capacity: 688.00 MiB
@@ -69,6 +101,46 @@ total_memory: 8.00 GiB
69101
compute_memory: 3.47 GiB
70102
reserved_memory: 2.40 GiB
71103
```
72-
</Accordion>
73-
</AccordionGroup>
74104

105+
For guidance on tuning memory allocation, see [Tune reserved memory](/operate/tune-reserved-memory).
106+
107+
<script type="application/ld+json">
108+
{JSON.stringify({
109+
"@context": "https://schema.org",
110+
"@type": "FAQPage",
111+
"mainEntity": [
112+
{
113+
"@type": "Question",
114+
"name": "Why is RisingWave memory usage so high?",
115+
"acceptedAnswer": {
116+
"@type": "Answer",
117+
"text": "This is by design. RisingWave uses memory for in-memory caching of streaming query state to optimize performance. By default, it utilizes all available memory unless configured via RW_TOTAL_MEMORY_BYTES. Setting memory limits is required in Kubernetes and Docker deployments."
118+
}
119+
},
120+
{
121+
"@type": "Question",
122+
"name": "Why is the memory for a RisingWave Serving or Streaming Node not fully utilized?",
123+
"acceptedAnswer": {
124+
"@type": "Answer",
125+
"text": "RisingWave reserves a portion of total memory for system usage. Starting from v1.10, it uses a gradient formula: 30% of the first 16GB plus 20% of the remaining memory. You can override this with the RW_RESERVED_MEMORY_BYTES environment variable or --reserved-memory-bytes startup option (minimum 512MB)."
126+
}
127+
},
128+
{
129+
"@type": "Question",
130+
"name": "Why does CREATE MATERIALIZED VIEW take a long time in RisingWave?",
131+
"acceptedAnswer": {
132+
"@type": "Answer",
133+
"text": "CREATE MATERIALIZED VIEW backfills all historical data from referenced tables to ensure a consistent snapshot. Use SHOW JOBS to check progress. To run non-blocking, set BACKGROUND_DDL=true before the CREATE statement. If progress stays at 0%, the cluster may be experiencing high latency."
134+
}
135+
},
136+
{
137+
"@type": "Question",
138+
"name": "What does RisingWave memory usage consist of?",
139+
"acceptedAnswer": {
140+
"@type": "Answer",
141+
"text": "RisingWave memory is divided into storage memory (block cache, meta cache, shared buffer), compute memory (streaming computation and queries), and reserved memory (system overhead). For example, an 8GB node uses approximately 2.13GB for storage, 3.47GB for compute, and 2.40GB reserved."
142+
}
143+
}
144+
]
145+
})}
146+
</script>

0 commit comments

Comments
 (0)