[DRAFT] POC / Get started onboarding revamp

docs/_snippets/_users-and-roles-common.md

@@ -42,64 +42,73 @@ Create these tables and users to be used in the examples.
 
 #### Creating a sample database, table, and rows {#creating-a-sample-database-table-and-rows}
 
-1. Create a test database
+<VerticalStepper headerLevel="h5">
 
-   ```sql
-   CREATE DATABASE db1;
-   ```
+##### Create a test database {#create-a-test-database}
 
-2. Create a table
+```sql
+CREATE DATABASE db1;
+```
 
-   ```sql
-   CREATE TABLE db1.table1 (
-       id UInt64,
-       column1 String,
-       column2 String
-   )
-   ENGINE MergeTree
-   ORDER BY id;
-   ```
+##### Create a table {#create-a-table}
 
-3. Populate the table with sample rows
+```sql
+CREATE TABLE db1.table1 (
+   id UInt64,
+   column1 String,
+   column2 String
+)
+ENGINE MergeTree
+ORDER BY id;
+```
 
-   ```sql
-   INSERT INTO db1.table1
-       (id, column1, column2)
-   VALUES
-       (1, 'A', 'abc'),
-       (2, 'A', 'def'),
-       (3, 'B', 'abc'),
-       (4, 'B', 'def');
-   ```
+##### Populate the table with sample rows {#populate}
 
-4. Verify the table:
+```sql
+INSERT INTO db1.table1
+   (id, column1, column2)
+VALUES
+   (1, 'A', 'abc'),
+   (2, 'A', 'def'),
+   (3, 'B', 'abc'),
+   (4, 'B', 'def');
+```
 
-   ```sql
-   SELECT *
-   FROM db1.table1
-   ```
+##### Verify the table {#verify}
 
-   ```response
-   Query id: 475015cc-6f51-4b20-bda2-3c9c41404e49
+```sql title="Query"
+SELECT *
+FROM db1.table1
+```
 
-   ┌─id─┬─column1─┬─column2─┐
-   │  1 │ A       │ abc     │
-   │  2 │ A       │ def     │
-   │  3 │ B       │ abc     │
-   │  4 │ B       │ def     │
-   └────┴─────────┴─────────┘
-   ```
+```response title="Response"
+Query id: 475015cc-6f51-4b20-bda2-3c9c41404e49
 
-5. Create a regular user that will be used to demonstrate restrict access to certain columns:
+┌─id─┬─column1─┬─column2─┐
+│  1 │ A       │ abc     │
+│  2 │ A       │ def     │
+│  3 │ B       │ abc     │
+│  4 │ B       │ def     │
+└────┴─────────┴─────────┘
+```
 
-   ```sql
-   CREATE USER column_user IDENTIFIED BY 'password';
-   ```
+##### Create `column_user` {#create-a-user-with-restricted-access-to-columns}
 
-6. Create a regular user that will be used to demonstrate restricting access to rows with certain values:
-   ```sql
-   CREATE USER row_user IDENTIFIED BY 'password';
-   ```
+Create a regular user that will be used to demonstrate restrict access to certain columns:
+
+```sql
+CREATE USER column_user IDENTIFIED BY 'password';
+```
+
+##### Create `row_user` {#create-a-user-with-restricted-access-to-rows-with-certain-values}
+
+Create a regular user that will be used to demonstrate restricting access to rows with certain values:
+
+```sql
+CREATE USER row_user IDENTIFIED BY 'password';
+```
+
+</VerticalStepper>
 
 #### Creating roles {#creating-roles}
 

docs/best-practices/_snippets/_table_of_contents.md

@@ -0,0 +1,12 @@
+| Page                                                                                 | Description                                                                                             |
+|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| [Choosing a Primary Key](/best-practices/choosing-a-primary-key)                     | How to select primary keys that maximize query performance and minimize storage overhead.               |
+| [Select Data Types](/best-practices/select-data-types)                               | Choose optimal data types to reduce memory usage, improve compression, and accelerate queries.          |
+| [Use Materialized Views](/best-practices/use-materialized-views)                     | Leverage materialized views to pre-aggregate data and dramatically speed up analytical queries.         |
+| [Minimize and Optimize JOINs](/best-practices/minimize-optimize-joins)               | Best practices for using ClickHouse's `JOIN` capabilities efficiently.                                  |
+| [Choosing a Partitioning Key](/best-practices/choosing-a-partitioning-key)           | Select partitioning strategies that enable efficient data pruning and faster query execution.           |
+| [Selecting an Insert Strategy](/best-practices/selecting-an-insert-strategy)         | Optimize data ingestion throughput and reduce resource consumption with proper insert patterns.         |
+| [Data Skipping Indices](/best-practices/use-data-skipping-indices-where-appropriate) | Apply secondary indices strategically to skip irrelevant data blocks and accelerate filtered queries.   |
+| [Avoid Mutations](/best-practices/avoid-mutations)                                   | Design schemas and workflows that eliminate costly `UPDATE`/`DELETE` operations for better performance. |
+| [Avoid OPTIMIZE FINAL](/best-practices/avoid-optimize-final)                         | Prevent performance bottlenecks by understanding when `OPTIMIZE FINAL` hurts more than it helps.        |
+| [Use JSON where appropriate](/best-practices/use-json-where-appropriate)             | Balance flexibility and performance when working with semi-structured JSON data in ClickHouse.          |

docs/best-practices/index.md

@@ -6,19 +6,10 @@ hide_title: true
 description: 'Landing page for Best Practices section in ClickHouse'
 ---
 
+import TableOfContents from '@site/docs/best-practices/_snippets/_table_of_contents.md';
+
 # Best Practices in ClickHouse {#best-practices-in-clickhouse}
 
 This section provides the best practices you will want to follow to get the most out of ClickHouse.
 
-| Page                                                                 | Description                                                              |
-|----------------------------------------------------------------------|--------------------------------------------------------------------------|
-| [Choosing a Primary Key](/best-practices/choosing-a-primary-key)     | Guidance on selecting an effective Primary Key in ClickHouse.            |
-| [Select Data Types](/best-practices/select-data-types)               | Recommendations for choosing appropriate data types.                     |
-| [Use Materialized Views](/best-practices/use-materialized-views)     | When and how to benefit from materialized views.                         |
-| [Minimize and Optimize JOINs](/best-practices/minimize-optimize-joins)| Best practices for minimizing and optimizing JOIN operations.            |
-| [Choosing a Partitioning Key](/best-practices/choosing-a-partitioning-key) | How to choose and apply partitioning keys effectively.              |
-| [Selecting an Insert Strategy](/best-practices/selecting-an-insert-strategy) | Strategies for efficient data insertion in ClickHouse.             |
-| [Data Skipping Indices](/best-practices/use-data-skipping-indices-where-appropriate) | When to apply data skipping indices for performance gains.    |
-| [Avoid Mutations](/best-practices/avoid-mutations)                   | Reasons to avoid mutations and how to design without them.               |
-| [Avoid OPTIMIZE FINAL](/best-practices/avoid-optimize-final)         | Why `OPTIMIZE FINAL` can be costly and how to work around it.           |
-| [Use JSON where appropriate](/best-practices/use-json-where-appropriate) | Considerations for using JSON columns in ClickHouse.               |
+<TableOfContents/>

docs/cloud/bestpractices/_category_.yml → docs/cloud/guides/_category_.yml

@@ -1,4 +1,4 @@
-label: 'Best Practices'
+label: 'Guides'
 collapsible: true
 collapsed: true
 link:

docs/cloud/guides/best_practices/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Best practices",
+  "collapsible": true,
+  "collapsed": true,
+}

docs/cloud/bestpractices/multitenancy.md → docs/cloud/guides/best_practices/multitenancy.md

@@ -1,6 +1,6 @@
 ---
 slug: /cloud/bestpractices/multi-tenancy
-sidebar_label: 'Implement multi tenancy'
+sidebar_label: 'Multi tenancy'
 title: 'Multi tenancy'
 description: 'Best practices to implement multi tenancy'
 ---

docs/cloud/guides/best_practices/usagelimits.md

@@ -0,0 +1,40 @@
+---
+slug: /cloud/bestpractices/usage-limits
+sidebar_label: 'Service limits'
+title: 'Usage limits'
+description: 'Describes the recommended usage limits in ClickHouse Cloud'
+---
+
+While ClickHouse is known for its speed and reliability, optimal performance is 
+achieved within certain operating parameters. For example, having too many tables,
+databases or parts could negatively impact performance. To avoid this, Clickhouse
+Cloud has guardrails set up for several types of items. You can find details of 
+these guardrails below.
+
+:::tip
+If you've run up against one of these guardrails, it's possible that you are 
+implementing your use case in an unoptimized way. Contact our support team and 
+we will gladly help you refine your use case to avoid exceeding the guardrails 
+or look together at how we can increase them in a controlled manner. 
+:::
+
+| Dimension                     | Limit                                                      |
+|-------------------------------|------------------------------------------------------------|
+| **Databases**                 | 1000                                                       |
+| **Tables**                    | 5000                                                       |
+| **Columns**                   | ∼1000 (wide format is preferred to compact)                |
+| **Partitions**                | 50k                                                        |
+| **Parts**                     | 100k across the entire instance                            |
+| **Part size**                 | 150gb                                                      |
+| **Services per organization** | 20 (soft)                                                  |
+| **Services per warehouse**    | 5 (soft)                                                   |
+| **Low cardinality**           | 10k or less                                                |
+| **Primary keys in a table**   | 4-5 that sufficiently filter down the data                 |
+| **Query concurrency**         | 1000                                                       |
+| **Batch ingest**              | anything > 1M will be split by the system in 1M row blocks |
+
+:::note
+For Single Replica Services, the maximum number of databases is restricted to 
+100, and the maximum number of tables is restricted to 500. In addition, storage
+for Basic Tier Services is limited to 1 TB.
+:::

docs/cloud/reference/cloud-compatibility.md → docs/cloud/guides/cloud-compatibility.md

@@ -1,6 +1,6 @@
 ---
 slug: /whats-new/cloud-compatibility
-sidebar_label: 'Cloud Compatibility'
+sidebar_label: 'Cloud compatibility'
 title: 'Cloud Compatibility'
 description: 'This guide provides an overview of what to expect functionally and operationally in ClickHouse Cloud.'
 ---

docs/cloud/guides/index.md

@@ -0,0 +1,22 @@
+---
+slug: /cloud/bestpractices
+keywords: ['Cloud', 'Best Practices', 'Bulk Inserts', 'Asynchronous Inserts', 'Avoid Mutations', 'Avoid Nullable Columns', 'Avoid Optimize Final', 'Low Cardinality Partitioning Key', 'Multi Tenancy', 'Usage Limits']
+title: 'Overview'
+hide_title: true
+description: 'Landing page for Best Practices section in ClickHouse Cloud'
+---
+
+import TableOfContents from '@site/docs/best-practices/_snippets/_table_of_contents.md';
+
+# Best Practices in ClickHouse Cloud {#best-practices-in-clickhouse-cloud}
+
+This section provides best practices you will want to follow to get the most out of ClickHouse Cloud.
+
+| Page                                                     | Description                                                                |
+|----------------------------------------------------------|----------------------------------------------------------------------------|
+| [Usage Limits](/cloud/bestpractices/usage-limits)| Explore the limits of ClickHouse.                                          |
+| [Multi tenancy](/cloud/bestpractices/multi-tenancy)| Learn about different strategies to implement multi-tenancy.                                          |
+
+These are in addition to the standard best practices which apply to all deployments of ClickHouse.
+
+<TableOfContents />

docs/cloud/guides/security/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Security",
+  "collapsible": true,
+  "collapsed": true,
+}

docs/cloud/guides/security/cloud_access_management/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Cloud Access Management",
+  "collapsible": true,
+  "collapsed": true,
+}

docs/cloud/guides/security/connectivity/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Connectivity",
+  "collapsible": true,
+  "collapsed": true,
+}