Getting started: Rework whole section #232
Conversation
WalkthroughThis change restructures the CrateDB documentation by introducing a new "start" section with dedicated pages for creating clusters, connecting, schema management, and querying. It updates navigation and link references to use internal inventory-style links, removes the old "getting-started" entry, and improves formatting and organization throughout the documentation. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant DocsIndex
participant StartSection
participant SubPages
User->>DocsIndex: Open documentation
DocsIndex->>StartSection: Display "Getting Started" section
StartSection->>SubPages: Show links (create, connect, schema, query)
User->>SubPages: Select topic (e.g., connect)
SubPages->>User: Display relevant instructions and links
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Suggested reviewers
Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🔭 Outside diff range comments (2)
docs/index.md (1)
307-319: Update hard-coded “getting-started” links to the new start slugThe old
getting-startedpage file has been removed (only the image assets folder remains), but there are still a few inbound links pointing at the old/docs/guide/getting-started.html. Please update these to point at the newstart/indexlocation:• docs/home/index.md (around line 158):
https://cratedb.com/docs/guide/getting-started.html→/docs/start/index.html(or appropriate relative ref)
• README.md (around line 9):
[Getting Started](https://cratedb.com/docs/guide/getting-started.html)→[Getting Started](/docs/start/index.html)Once these are updated, the cleanup for
getting-startedshould be complete.docs/start/connect.md (1)
31-34: Replace fragment link with a{ref}cross‐reference to thecreate-userlabelThe
create-useranchor is defined indocs/admin/create-user.md, so using{ref}ensures a stable, resolved link instead of a raw fragment.• File:
docs/start/connect.md, lines 31–34
• Uses existing label(create-user)=indocs/admin/create-user.md:::{note} If you are running CrateDB on a remote machine, you will have to create -a dedicated user account for accessing the Admin UI. See [](#create-user). +a dedicated user account for accessing the Admin UI. See {ref}`create-user`. :::
🧹 Nitpick comments (5)
docs/start/query.md (1)
6-10: Ref is correct; add one minimal query example for quick win.The {ref} to
crate-reference:sqlis appropriate. Consider adding a tiny runnable example to make this page actionable for newcomers.SQL is the most widely used language for querying data and is the natural choice for people in many roles working with data in databases. CrateDB extends industry-standard SQL with functionalities to support its data types, data I/O procedures, and cluster management. To learn more, check out the {ref}`SQL syntax reference manual <crate-reference:sql>`. + +## Quick example + +```sql +SELECT name, COUNT(*) AS cnt +FROM doc.customers +GROUP BY name +ORDER BY cnt DESC +LIMIT 5; +```Happy to add a few more examples covering filtering and joins if you want.
docs/start/schema.md (1)
8-16: Add a cross-reference to the Privileges docs and confirm schema-level GRANT behaviorPlease verify that CrateDB indeed treats schemas as implicit namespaces and accepts any schema name in
GRANT/DENY/REVOKEstatements without further validation. Once confirmed, update the documentation as follows:
In
docs/start/schema.md, immediately after the sentence:“…when
GRANT,DENYorREVOKEare invoked on a schema level,
CrateDB takes the schema name provided without further validation.”append:
See [Privileges] for details.In
docs/_include/links.md, add the new link entry:[Privileges]: inv:crate-reference#administration-privileges(This matches the existing anchor used elsewhere in the docs.)
docs/start/create.md (2)
6-9: Grammar: “fastest and easy” → “fastest and easiest”.Tighten the sentence.
-The fastest and easy way is to create a [CrateDB Cloud cluster][CrateDB Cloud Console]. +The fastest and easiest way is to create a [CrateDB Cloud cluster][CrateDB Cloud Console].
10-11: Tone/style nit: drop “please” for concision.Optional, but keeps a neutral, concise tone used elsewhere.
-Basic support is included. If you need premium support, please [check out our support plans]. +Basic support is included. For premium support, [check out our support plans].docs/start/connect.md (1)
1-1: Title grammar: “Connect to a cluster”.Minor readability improvement.
-# Connect to cluster +# Connect to a cluster
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
docs/_include/links.md(2 hunks)docs/index.md(1 hunks)docs/start/connect.md(2 hunks)docs/start/create.md(1 hunks)docs/start/index.md(1 hunks)docs/start/query.md(1 hunks)docs/start/schema.md(1 hunks)
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
📚 Learning: 2025-05-18T12:50:36.393Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Applied to files:
docs/start/index.mddocs/start/query.mddocs/start/connect.mddocs/_include/links.mddocs/start/schema.mddocs/start/create.md
📚 Learning: 2025-05-18T12:50:38.681Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Applied to files:
docs/start/index.mddocs/start/query.mddocs/start/connect.mddocs/_include/links.mddocs/start/schema.mddocs/start/create.md
📚 Learning: 2025-08-06T02:11:46.794Z
Learnt from: amotl
PR: crate/cratedb-guide#222
File: docs/integrate/powerbi/index.md:16-23
Timestamp: 2025-08-06T02:11:46.794Z
Learning: The `project:` role in MyST Markdown syntax like `[](project:#powerbi-desktop)` and `[](project:#powerbi-service)` is valid cross-reference syntax in the CrateDB Guide repository's MyST Markdown setup.
Applied to files:
docs/start/index.mddocs/start/connect.mddocs/_include/links.md
📚 Learning: 2025-06-05T14:29:15.512Z
Learnt from: amotl
PR: crate/cratedb-guide#207
File: docs/integrate/etl/iceberg-risingwave.md:205-207
Timestamp: 2025-06-05T14:29:15.512Z
Learning: The `records.Database("crate://", echo=True)` connection string for CrateDB works with defaults: localhost as host, "crate" as user, and blank password. This is valid and functional code in the records library.
Applied to files:
docs/start/connect.mddocs/_include/links.md
📚 Learning: 2025-08-05T07:14:57.416Z
Learnt from: hammerhead
PR: crate/cratedb-guide#221
File: docs/connect/configure.md:58-66
Timestamp: 2025-08-05T07:14:57.416Z
Learning: In CrateDB connection strings, the user:password@ syntax is valid for HTTP Basic authentication on port 4200, but PostgreSQL JDBC drivers do not support this format and require credentials as query parameters (?user=<user>&password=<password>) instead.
Applied to files:
docs/start/connect.mddocs/_include/links.md
📚 Learning: 2025-05-18T13:25:11.786Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
Applied to files:
docs/start/connect.mddocs/_include/links.mddocs/start/create.md
🪛 markdownlint-cli2 (0.17.2)
docs/start/connect.md
8-8: Link fragments should be valid
(MD051, link-fragments)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build docs
🔇 Additional comments (9)
docs/_include/links.md (1)
13-13: Good move to centralize the Reference Manual link.Switching to
inv:crate-reference:*:label#indexkeeps the link durable across versions.docs/start/index.md (3)
1-3: Keeping both(use)=and(getting-started)=labels is smart for backwards compat.This preserves existing cross-refs without breaking links.
16-19: Consistent internal reference to the Reference Manual.Using a central link reference with the
inv:syntax is aligned with the repo’s pattern.Also applies to: 22-22
5-13: ToC targets verified
All referenced files indocs/startexist:
- connect.md
- create.md
- schema.md
- query.md
No missing targets detected.
docs/start/schema.md (1)
18-20: WIP note is fine.Clear signal to readers; OK to ship as-is.
docs/start/create.md (1)
17-18: Cross-reference labels verified forinstallandinstall-cloud
The Sphinx targets are defined here, so{ref}links will resolve correctly:
.. _install:in docs/install/index.rst.. _install-cloud:in docs/install/cloud/index.rstNo broken refs—no changes required.
docs/start/connect.md (3)
14-17: Admin UI link via inventory looks good.Linking through [Admin UI] (from links include) keeps references consistent.
39-43: Good: use intersphinx for crash docs.{ref}
crate-crash:indexis preferable over hardcoded URLs.
49-55: Adapters/drivers pointers look clear and concise.Solid routing to {ref}
connectand the reference manual.
| # Create table schema | ||
|
|
||
| In CrateDB you can create a table within a schema like | ||
| ```sql | ||
| CREATE TABLE schema_name.table_name; | ||
| ``` |
There was a problem hiding this comment.
SQL snippet is syntactically invalid; provide a minimal valid CREATE TABLE.
CREATE TABLE schema_name.table_name; will fail without columns (or AS SELECT). Use a minimal, valid example to prevent copy/paste errors.
-# Create table schema
+# Create tables in a schema
...
-```sql
-CREATE TABLE schema_name.table_name;
-```
+```sql
+CREATE TABLE schema_name.table_name (
+ id INTEGER PRIMARY KEY,
+ name TEXT
+);
+```Renamed the heading for clarity.
🤖 Prompt for AI Agents
In docs/start/schema.md lines 1 to 6, the provided SQL snippet for creating a
table is invalid because it lacks column definitions. Replace the snippet with a
minimal valid CREATE TABLE statement including at least one column and a primary
key, for example, define columns like "id INTEGER PRIMARY KEY" and "name TEXT"
within parentheses, and ensure the code block is properly fenced with ```sql at
start and ``` at end.
There was a problem hiding this comment.
I'd suggest the same here. Maybe even a nicer example so people can follow the getting started section and get a working example at the end.
There was a problem hiding this comment.
Yeah. Can we ask you to add some love here? We are super busy getting everything on track across the board, so we'd love to see people contributing on the most prominent details where gaps can be observed.
If you can find some time to make it happen, just submit a PR with your changes derived from and directed to this branch, getting-started. 🍀
There was a problem hiding this comment.
Of course! I can help with that =]
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/_include/links.md (1)
1-1: Silence markdownlint MD053 for this include fileThis file intentionally defines shared link references, so MD053 (“unused link reference definitions”) is noisy. Suppress it locally to keep CI clean.
Option A — add a file-scoped directive at the top:
+<!-- markdownlint-disable MD053 --> +<!-- Central link reference registry (used across the docs set) --> [Admin UI]: inv:crate-admin-ui:*:label#indexOption B — add an override in .markdownlint.json:
{ "overrides": [ { "files": ["docs/_include/links.md"], "MD053": false } ] }Also applies to: 11-11, 13-13
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
docs/_include/links.md(2 hunks)docs/index.md(1 hunks)docs/start/connect.md(2 hunks)docs/start/create.md(1 hunks)docs/start/index.md(1 hunks)docs/start/query.md(1 hunks)docs/start/schema.md(1 hunks)
✅ Files skipped from review due to trivial changes (3)
- docs/start/schema.md
- docs/start/index.md
- docs/start/create.md
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/index.md
- docs/start/query.md
- docs/start/connect.md
🧰 Additional context used
🧠 Learnings (9)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.637Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-admin-ui` are inherited from the root project `crate-docs-theme` rather than being defined locally in `docs/conf.py`. This allows shared documentation configurations across multiple CrateDB documentation projects.
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.282Z
Learning: In the CrateDB Guide repository, intersphinx mappings like "cloud" are defined within the root project `crate-docs-theme` and inherited by the documentation projects, so they don't need to be explicitly defined in individual `docs/conf.py` files.
📚 Learning: 2025-08-07T23:11:09.637Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.637Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-admin-ui` are inherited from the root project `crate-docs-theme` rather than being defined locally in `docs/conf.py`. This allows shared documentation configurations across multiple CrateDB documentation projects.
Applied to files:
docs/_include/links.md
📚 Learning: 2025-05-18T12:50:36.393Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Applied to files:
docs/_include/links.md
📚 Learning: 2025-05-18T12:50:38.681Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Applied to files:
docs/_include/links.md
📚 Learning: 2025-08-07T23:11:08.282Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.282Z
Learning: In the CrateDB Guide repository, intersphinx mappings like "cloud" are defined within the root project `crate-docs-theme` and inherited by the documentation projects, so they don't need to be explicitly defined in individual `docs/conf.py` files.
Applied to files:
docs/_include/links.md
📚 Learning: 2025-08-06T02:11:46.794Z
Learnt from: amotl
PR: crate/cratedb-guide#222
File: docs/integrate/powerbi/index.md:16-23
Timestamp: 2025-08-06T02:11:46.794Z
Learning: The `project:` role in MyST Markdown syntax like `[](project:#powerbi-desktop)` and `[](project:#powerbi-service)` is valid cross-reference syntax in the CrateDB Guide repository's MyST Markdown setup.
Applied to files:
docs/_include/links.md
📚 Learning: 2025-06-05T14:29:15.512Z
Learnt from: amotl
PR: crate/cratedb-guide#207
File: docs/integrate/etl/iceberg-risingwave.md:205-207
Timestamp: 2025-06-05T14:29:15.512Z
Learning: The `records.Database("crate://", echo=True)` connection string for CrateDB works with defaults: localhost as host, "crate" as user, and blank password. This is valid and functional code in the records library.
Applied to files:
docs/_include/links.md
📚 Learning: 2025-08-05T07:14:57.416Z
Learnt from: hammerhead
PR: crate/cratedb-guide#221
File: docs/connect/configure.md:58-66
Timestamp: 2025-08-05T07:14:57.416Z
Learning: In CrateDB connection strings, the user:password@ syntax is valid for HTTP Basic authentication on port 4200, but PostgreSQL JDBC drivers do not support this format and require credentials as query parameters (?user=<user>&password=<password>) instead.
Applied to files:
docs/_include/links.md
📚 Learning: 2025-05-18T13:25:11.786Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
Applied to files:
docs/_include/links.md
🪛 markdownlint-cli2 (0.17.2)
docs/_include/links.md
1-1: Link and image reference definitions should be needed
Unused link or image reference definition: "admin ui"
(MD053, link-image-reference-definitions)
11-11: Link and image reference definitions should be needed
Unused link or image reference definition: "cratedb cloud"
(MD053, link-image-reference-definitions)
12-12: Link and image reference definitions should be needed
Unused link or image reference definition: "cratedb jdbc driver"
(MD053, link-image-reference-definitions)
13-13: Link and image reference definitions should be needed
Unused link or image reference definition: "cratedb reference manual"
(MD053, link-image-reference-definitions)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build docs
🔇 Additional comments (3)
docs/_include/links.md (3)
1-1: LGTM: Use intersphinx for Admin UIUsing inv:crate-admin-ui is correct given theme-level intersphinx mappings. No action needed.
11-11: LGTM: Switch “CrateDB Cloud” to inventory linkinv:cloud is consistent with the new link style and relies on theme-provided mappings. Looks good.
13-13: LGTM: Add “CrateDB Reference Manual” inventory linkGood addition; aligns with cross-project intersphinx usage.
amotl
added
enhancement
|
This PR has been accidentally closed. Apologies. The new PR is: |
2 participants
About
The "getting started" section was a bit thin. This patch aims to give it more volume based on suggestions by colleagues.
Source: https://cratedb.gitbook.io/cratedb-docs/K3l1K4ZBSqj0AL16dbZi/getting-started
Preview: https://cratedb-guide--232.org.readthedocs.build/start/
References