Getting started: Rework whole section (GenAI, edited) #235
Conversation
WalkthroughAdded a Getting Started hub under Changes
Sequence Diagram(s)sequenceDiagram
participant User as Developer/Reader
participant Homepage as docs/index.md
participant StartHub as docs/start/index.md
participant Connect as docs/start/connect.md
participant QueryHub as docs/start/query/index.md
rect rgba(238,248,255,0.9)
Note over StartHub,QueryHub: New Getting Started hub + Query subpages
end
User->>Homepage: open docs homepage
Homepage->>StartHub: click "Getting Started"
StartHub->>Connect: open "Connect to CrateDB"
StartHub->>QueryHub: open "Query capabilities"
QueryHub->>QueryHub: navigate -> Aggregations / Ad-hoc / AI-integration
Connect->>User: render Admin UI, crash, drivers links (inv: refs)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ 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/Issue comments)Type 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: 3
🔭 Outside diff range comments (1)
docs/start/connect.md (1)
31-34: Replace broken local anchor with proper cross-referenceThe “create-user” section is defined in docs/admin/create-user.md with the label
(create-user)=. Update the note in docs/start/connect.md to reference that label:-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). +If you are running CrateDB on a remote machine, you will have to create +a dedicated user account for accessing the Admin UI. See {ref}`create-user`.• File: docs/start/connect.md
• Lines: 31–34
🧹 Nitpick comments (9)
docs/start/index.md (1)
16-19: Avoid duplicate link reference definitions; rely on the central links include.You define [CrateDB Reference Manual] here and it’s also defined globally in docs/_include/links.md. Prefer the central include to prevent duplicate-definition warnings and drift.
-:::{note} -To learn more about all the details of CrateDB features, operations, and -its SQL dialect, please also visit the [CrateDB Reference Manual]. -::: - -[CrateDB Reference Manual]: inv:crate-reference:*:label#index +:::{note} +To learn more about all the details of CrateDB features, operations, and +its SQL dialect, please also visit the [CrateDB Reference Manual]. +:::Also applies to: 22-22
docs/start/create.md (2)
20-24: Consistent linking to support plans.Link is correct; consider consolidating this common link via docs/_include/links.md to keep references centralized.
6-11: Nit: grammar fix & verify intersphinx targetcloud:quick-startPlease update the wording and double-check that the
cloud:quick-startreference actually exists in the CrateDB Cloud docs intersphinx inventory.• File docs/start/create.md:
- Line 6: Change “The fastest and easy way” → “The fastest and easiest way”
- Line 7: Ensure the
{ref}target<cloud:quick-start>is defined in the Cloud docs-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]. See also documentation about {ref}`creating a new cluster in CrateDB Cloud <cloud:quick-start>`.docs/start/query.md (1)
12-14: WIP notice is fine; consider adding a minimal example.A one-paragraph SELECT example would make this page immediately actionable without waiting for full content.
docs/start/schema.md (4)
1-1: Title wording: make it clear and idiomatic“Create table schema” reads awkwardly. Recommend “Schemas and tables” or “Create tables in schemas” for clarity and searchability.
-# Create table schema +# Schemas and tables
1-1: Include shared link refs/styles for consistencyMost start pages include the shared includes. Add them to keep link references like [CrateDB Reference Manual] available and consistent styling.
+# :::{include} /_include/links.md +# ::: +# :::{include} /_include/styles.html +# ::: # Schemas and tables
8-11: Privilege example is fine; consider showing DML/DDL, tooDQL is read-only. A second example for write access (DML) improves clarity.
```sql GRANT DQL ON SCHEMA schema_name TO user_name;+
sql +-- Allow writes (INSERT/UPDATE/DELETE): +GRANT DML ON SCHEMA schema_name TO user_name; +--- `18-20`: **Note block: keep, but consider linking to reference docs** If possible, link to the CREATE TABLE and PRIVILEGES docs via intersphinx for readers to dive deeper. Would you like me to add those references using your project’s intersphinx mappings? </blockquote></details> <details> <summary>docs/start/connect.md (1)</summary><blockquote> `1-1`: **Title grammar: add article** “Connect to cluster” → “Connect to a cluster”. ```diff -# 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 (10)
📓 Common learnings
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#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
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.657Z
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#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#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
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-08T16:50:14.965Z
Learnt from: amotl
PR: crate/cratedb-guide#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
Applied to files:
docs/start/index.mddocs/start/create.mddocs/_include/links.mddocs/start/connect.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/start/index.mddocs/start/query.mddocs/start/schema.mddocs/start/create.mddocs/_include/links.mddocs/start/connect.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/schema.mddocs/start/create.mddocs/_include/links.mddocs/start/connect.md
📚 Learning: 2025-08-07T23:11:09.657Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
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/start/index.mddocs/start/schema.mddocs/start/create.mddocs/_include/links.mddocs/start/connect.md
📚 Learning: 2025-08-07T23:11:08.311Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
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/start/index.mddocs/start/create.mddocs/_include/links.mddocs/start/connect.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/_include/links.mddocs/start/connect.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/create.mddocs/_include/links.mddocs/start/connect.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.mddocs/start/connect.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.mddocs/start/connect.md
🪛 markdownlint-cli2 (0.17.2)
docs/start/connect.md
1-1: Link and image reference definitions should be needed
Unused link or image reference definition: "admin ui"
(MD053, link-image-reference-definitions)
2-2: Link and image reference definitions should be needed
Unused link or image reference definition: "amazon dynamodb streams"
(MD053, link-image-reference-definitions)
3-3: Link and image reference definitions should be needed
Unused link or image reference definition: "amazon kinesis data streams"
(MD053, link-image-reference-definitions)
4-4: Link and image reference definitions should be needed
Unused link or image reference definition: "aws database migration service (aws dms)"
(MD053, link-image-reference-definitions)
5-5: Link and image reference definitions should be needed
Unused link or image reference definition: "aws dms integration with cratedb"
(MD053, link-image-reference-definitions)
6-6: Link and image reference definitions should be needed
Unused link or image reference definition: "bm25"
(MD053, link-image-reference-definitions)
7-7: Link and image reference definitions should be needed
Unused link or image reference definition: "cloud-datashader-colab"
(MD053, link-image-reference-definitions)
8-8: Link and image reference definitions should be needed
Unused link or image reference definition: "cloud-datashader-github"
(MD053, link-image-reference-definitions)
9-9: Link and image reference definitions should be needed
Unused link or image reference definition: "cte"
(MD053, link-image-reference-definitions)
10-10: Link and image reference definitions should be needed
Unused link or image reference definition: "cratedb blobs"
(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)
14-14: Link and image reference definitions should be needed
Unused link or image reference definition: "cratedb self-managed"
(MD053, link-image-reference-definitions)
15-15: Link and image reference definitions should be needed
Unused link or image reference definition: "cratedb's postgresql interface"
(MD053, link-image-reference-definitions)
16-16: Link and image reference definitions should be needed
Unused link or image reference definition: "crate-jdbc-standalone"
(MD053, link-image-reference-definitions)
17-17: Link and image reference definitions should be needed
Unused link or image reference definition: "crate-jdbc-standalone-latest.jar"
(MD053, link-image-reference-definitions)
38-38: Link and image reference definitions should be needed
Unused link or image reference definition: "langchain-similarity-colab"
(MD053, link-image-reference-definitions)
39-39: Link and image reference definitions should be needed
Unused link or image reference definition: "langchain-similarity-github"
(MD053, link-image-reference-definitions)
40-40: Link and image reference definitions should be needed
Unused link or image reference definition: "langchain-rag-sql-binder"
(MD053, link-image-reference-definitions)
41-41: Link and image reference definitions should be needed
Unused link or image reference definition: "langchain-rag-sql-colab"
(MD053, link-image-reference-definitions)
42-42: Link and image reference definitions should be needed
Unused link or image reference definition: "langchain-rag-sql-github"
(MD053, link-image-reference-definitions)
43-43: Link and image reference definitions should be needed
Unused link or image reference definition: "mongodb cdc relay"
(MD053, link-image-reference-definitions)
44-44: Link and image reference definitions should be needed
Unused link or image reference definition: "mongodb change streams"
(MD053, link-image-reference-definitions)
45-45: Link and image reference definitions should be needed
Unused link or image reference definition: "mongodb table loader"
(MD053, link-image-reference-definitions)
46-46: Link and image reference definitions should be needed
Unused link or image reference definition: "multi-model database"
(MD053, link-image-reference-definitions)
47-47: Link and image reference definitions should be needed
Unused link or image reference definition: "nearest neighbor search"
(MD053, link-image-reference-definitions)
48-48: Link and image reference definitions should be needed
Unused link or image reference definition: "nested data structure"
(MD053, link-image-reference-definitions)
49-49: Link and image reference definitions should be needed
Unused link or image reference definition: "postgresql jdbc driver"
(MD053, link-image-reference-definitions)
50-50: Link and image reference definitions should be needed
Unused link or image reference definition: "python-dbapi-by-example"
(MD053, link-image-reference-definitions)
51-51: Link and image reference definitions should be needed
Unused link or image reference definition: "python-sqlalchemy-by-example"
(MD053, link-image-reference-definitions)
52-52: Link and image reference definitions should be needed
Unused link or image reference definition: "query dsl based on json"
(MD053, link-image-reference-definitions)
53-53: Link and image reference definitions should be needed
Unused link or image reference definition: "rank"
(MD053, link-image-reference-definitions)
54-54: Link and image reference definitions should be needed
Unused link or image reference definition: "relational database"
(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 (9)
docs/index.md (1)
307-319: No stale references togetting-startedfound
The only remaininglink: getting-startedin docs/index.md points to the new docs/start/index.md via its(getting-started)=label on that page, and there are no outdated toctree entries or orphaned pages. Everything resolves correctly—approving these changes.docs/_include/links.md (1)
1-1: Confirm intersphinx mappings for referenced inventoriesI ran the grep script against
docs/_include/links.mdand found theseinv:projects in use:
- crate-admin-ui
- cloud
- crate-reference
- crate-python
- sqlalchemy-cratedb
Please verify that each of these names is defined in the shared crate-docs-theme’s intersphinx_mapping and that the
*:label#indextargets exist and resolve successfully at build time. There are no duplicate link definitions in this include file.docs/start/index.md (1)
5-13: All Toctree targets resolve correctly
- docs/start/create.md → H1 “Create a cluster” found
- docs/start/connect.md → H1 “Connect to cluster” found
- docs/start/schema.md → H1 “Create table schema” found
- docs/start/query.md → H1 “Querying data” found
- docs/ingest/index.md → H1 “CrateDB data ingestion” and
(ingest)=label presentNo further changes needed.
docs/start/create.md (1)
15-19: Internal refs verified – no changes neededThe
{ref}targetsinstallandinstall‐cloudare both defined and resolve correctly:
installlabel is indocs/install/index.rstinstall-cloudlabel is indocs/install/cloud/index.rstNo further fixes required.
docs/start/query.md (1)
6-10: Confirmedcrate-reference:sqlis correct and used consistently.
Thecrate-reference:sqllabel appears elsewhere (e.g., docs/feature/sql/index.md) to reference the SQL syntax manual. No changes required.docs/start/connect.md (4)
3-6: Includes look goodUsing shared links and styles is consistent with other start pages.
14-17: Admin UI link usage looks consistentUsing the [Admin UI] reference from shared links is correct.
49-55: Section and references LGTM“Adapters and drivers” plus {ref}
connectand the [CrateDB Reference Manual] link are consistent with the restructuring.
8-8: Reference ‘install’ target is validI’ve confirmed that the
{ref}labelinstallcorrectly resolves to the main installation page (install/index.md), so no changes are needed here.
amotl
added
help wanted
amotl
force-pushed
the
ingest
branch
2 times, most recently
from
1a91451 to
dedb05a
Compare
|
I'm not sure if we should start implementing things from the gitbook, afaik it's just a sketchbook which we will evaluate and decide later.. |
|
All right. My intention was to get the ball rolling, but let's convert this back to draft mode for now. Even if the content pieces are not ready yet, the ramblings on the sketchbook have been very worthwhile already to shape the page section layout here, by expanding from the existing status quo (where we just had a single page!), to make progress. Thank you! 
|
amotl
force-pushed
the
getting-started
branch
3 times, most recently
from
61f6def to
8ca08b1
Compare
amotl
force-pushed
the
getting-started
branch
2 times, most recently
from
4b40a92 to
80aca5b
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
docs/start/connect.md (1)
38-42: Confirm intersphinx key for CrateDB Shell; likelycrash:index(notcrate-crash:index)There’s prior discussion that the intersphinx mapping key is
crash. Please verify against crate-docs-theme. If confirmed, switch to{ref}crash:index``. Alternatively, consider centralizing this link via links.md like the Admin UI link for consistency.In crate-docs-theme (used by CrateDB Guide), what is the intersphinx mapping key for the CrateDB Shell (Crash) docs? Is it `crash` or `crate-crash`?Proposed change if confirmed:
- about it, please refer to its documentation at {ref}`crate-crash:index`. + about it, please refer to its documentation at {ref}`crash:index`.
📜 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 as they are similar to previous changes (6)
- docs/start/schema.md
- docs/_include/links.md
- docs/start/create.md
- docs/start/query.md
- docs/index.md
- docs/start/index.md
🧰 Additional context used
🧠 Learnings (6)
📚 Learning: 2025-08-09T10:59:42.066Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/connect/ide.md:2-2
Timestamp: 2025-08-09T10:59:42.066Z
Learning: In the CrateDB Guide documentation, legacy anchor labels (like `(ide)=`) should be retained alongside newer, more specific ones (like `(connect-ide)=`) to maintain backward compatibility for external projects that might reference them, even if they appear redundant within the repository.
Applied to files:
docs/start/connect.md
📚 Learning: 2025-08-08T16:50:14.965Z
Learnt from: amotl
PR: crate/cratedb-guide#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
Applied to files:
docs/start/connect.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/start/connect.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/connect.md
📚 Learning: 2025-08-07T23:11:09.657Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
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/start/connect.md
📚 Learning: 2025-08-07T23:11:08.311Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
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/start/connect.md
🔇 Additional comments (2)
docs/start/connect.md (2)
3-6: Includes look goodIncludes for shared links and styles at the top are consistent with the project setup.
49-55: Confirmed internal reference and link style
- The
(connect)label is defined in docs/connect/index.md, so{ref}connect`` resolves correctly.- Using
{ref}for internal cross-references and reference-style links for the CrateDB Reference Manual aligns with our documentation conventions.No changes required.
amotl
force-pushed
the
getting-started
branch
3 times, most recently
from
57569ee to
7b82b04
Compare
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (14)
docs/start/applications.md (2)
4-12: MyST/Sphinx-design grid is fine; minor copy cleanups suggestedStructure renders with sphinx-design. Two small nits to tighten the copy.
Apply this diff:
-:link: https://github.com/crate/crate-sample-apps -A JavaScript guestbook app with a number of different backend implementations, -each using a different client library to communicate with CrateDB. +:link: https://github.com/crate/crate-sample-apps +A JavaScript guestbook app with several backend implementations, +each using a different client library to communicate with CrateDB.
4-12: Consider switching to directive fences for grids to avoid linter noise on bare URLsmarkdownlint flags the bare URL in the option field. Using directive fences tends to reduce such false positives and aligns with existing patterns elsewhere.
Example:
```{grid} ```{grid-item-card} :link: https://github.com/crate/crate-sample-apps A JavaScript guestbook app with several backend implementations, each using a different client library to communicate with CrateDB.docs/start/first-steps.md (3)
9-11: Duplicate intro text; choose one to avoid redundancyFront-matter description (Lines 1–5) already states the same idea as Lines 9–11. Consider trimming the body intro or varying the wording to avoid repetition.
26-33: Jinja templating variabletutorialmay not be definedThe
{{ '{}(#objects-basics)'.format(tutorial) }}pattern assumes Jinja rendering with atutorialvariable in context. If Jinja/myst substitutions are not configured, this will render literally.
- If Jinja is enabled, confirm
tutorialis provided for this page.- If not, replace with standard cross-refs, e.g., {ref}
objects-basics.I can propose a Jinja-free variant if you prefer.
56-57: Remove unused link reference definition or use it
[check out our support plans]:is defined but unused; markdownlint flags it (MD053).Either use it in the body or remove it. To remove:
-[check out our support plans]: https://cratedb.com/support/support-plansdocs/start/query/ad-hoc-queries.md (2)
114-118: Tighten guidance on indexing and profiling“Fields are indexed by default” can be misleading; CrateDB indexing varies by type and settings. Also, confirm availability of ANALYZE variant.
Apply this refinement:
-| Leverage indexes | Fields are indexed by default—use them! | -| Avoid SELECT \* | Select only the fields you need | -| Profile queries | Use `EXPLAIN` and `ANALYZE` to inspect performance | +| Leverage indexing | Use primary keys, partitioning, and indexes on hot fields | +| Avoid SELECT \* | Select only the fields you need | +| Profile queries | Use `EXPLAIN` (and `EXPLAIN ANALYZE` if available) |To verify
EXPLAIN ANALYZEsupport in your version, please confirm against the SQL reference or run a quick check in a dev cluster.
160-164: Replace placeholders with real links for “Learn More”Consider linking to the internal SQL Reference and Console via your links inventory to improve UX.
Example:
- [CrateDB SQL Reference]
- [Admin UI Console]
- Blog: link to a relevant post
- CrateDB Academy: link to the appropriate course
docs/start/query/ai-integration.md (2)
13-13: Verifyproject:#vector-searchlink targetIf
{ref}is not appropriate because the target lives in another project, use the corresponding intersphinx/inventory role instead. Otherwise, keep{ref}pointing to a local label.I can adjust the link role once you confirm where “Vector Search” lives (this guide vs. another docs project).
106-116: Minor formatting nit in heading“Real-Time Inference with Hybrid** Queries” renders odd bolding. Make the whole phrase bold or none.
-### **Real-Time Inference with Hybrid** Queries +### **Real-Time Inference with Hybrid Queries**docs/start/query/aggregations.md (4)
54-61: Make “Nested / Object Field Aggregation” a proper subheadingAligns with the other pattern sections and improves ToC/anchors.
-**Nested / Object Field Aggregation** +### **Nested / Object Field Aggregation**
82-88: Prefer explicit interval arithmetic for dates
CURRENT_DATE - 30may be ambiguous. Using an interval is clearer and portable.-WHERE order_date >= CURRENT_DATE - 30 +WHERE order_date >= CURRENT_DATE - INTERVAL '30 days'
127-131: Percentile argument scale: verify and adjustCrateDB’s
PERCENTILE()commonly expects a 0–100 percentile value; using95is typical vs0.95. Please verify your version.-SELECT PERCENTILE(response_time, 0.95) AS p95 +SELECT PERCENTILE(response_time, 95) AS p95If your deployment uses 0–1 scale, keep
0.95.
11-18: Indexing wording: tone down “automatic indexing of fields”To avoid overpromising, suggest phrasing that acknowledges configuration.
-| Smart indexing | Automatic indexing of fields and user-defined indexes boost performance | +| Smart indexing | Built-in indexing plus user-defined indexes can boost performance |docs/start/connect.md (1)
11-16: Prefer MyST labels over HTML IDs; fix downstream note link
{#use-admin-ui}creates an HTML anchor but not a Sphinx ref target. Use a label so other pages can{ref}it. Also, the note later links to#create-userwhich isn't defined here; use a proper{ref}if it lives elsewhere.Apply:
-{#use-admin-ui} +(use-admin-ui)= ## Admin UIAnd update the note text in Lines 31-33 to:
- 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`.Ensure a
(create-user)=label exists on the target page, or add{#create-user}here if it’s a same-page section.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (12)
docs/_include/links.md(2 hunks)docs/index.md(1 hunks)docs/start/applications.md(1 hunks)docs/start/connect.md(2 hunks)docs/start/first-steps.md(1 hunks)docs/start/going-further.md(1 hunks)docs/start/index.md(1 hunks)docs/start/query/ad-hoc-queries.md(1 hunks)docs/start/query/aggregations.md(1 hunks)docs/start/query/ai-integration.md(1 hunks)docs/start/query/index.md(1 hunks)docs/start/query/search.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/start/query/search.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/index.md
- docs/_include/links.md
🧰 Additional context used
🧠 Learnings (12)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/start/first-steps.mddocs/start/going-further.mddocs/start/index.md
📚 Learning: 2025-08-08T16:50:14.965Z
Learnt from: amotl
PR: crate/cratedb-guide#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
Applied to files:
docs/start/connect.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/start/connect.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/connect.md
📚 Learning: 2025-08-07T23:11:09.657Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
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/start/connect.md
📚 Learning: 2025-08-07T23:11:08.311Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
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/start/connect.md
📚 Learning: 2025-08-09T11:03:33.178Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/ingest/etl/index.md:22-23
Timestamp: 2025-08-09T11:03:33.178Z
Learning: In the CrateDB Guide documentation, MyST Markdown files can use `{ref}` directives to reference labels defined in reStructuredText files using the RST syntax `.. _label:`. This cross-format referencing between MyST and RST is supported by Sphinx.
Applied to files:
docs/start/connect.md
📚 Learning: 2025-08-09T11:00:03.578Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/index.md:312-316
Timestamp: 2025-08-09T11:00:03.578Z
Learning: In the CrateDB Guide documentation, locally stale references (such as `(reference-architectures)=`, `(domain)=`, and similar anchor labels) should be retained even when they appear unused within the repository, as external projects might still reference them. This ensures backward compatibility for external documentation and projects.
Applied to files:
docs/start/connect.md
📚 Learning: 2025-08-09T21:40:46.154Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/streamsets/index.md:18-21
Timestamp: 2025-08-09T21:40:46.154Z
Learning: In the CrateDB Guide documentation, reStructuredText files (`.rst`) use the RST label syntax `.. _label:` while MyST Markdown files (`.md`) use the syntax `(label)=`. Both formats are used throughout the repository and labels can be cross-referenced between them.
Applied to files:
docs/start/connect.md
📚 Learning: 2025-08-10T17:09:32.616Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/azure-functions/index.md:31-36
Timestamp: 2025-08-10T17:09:32.616Z
Learning: In the CrateDB Guide documentation, RST files (`.rst`) use reStructuredText anchor syntax `.. _anchor-name:` while Markdown files (`.md`) use MyST syntax `(anchor-name)=`. Cross-references between MyST Markdown and reStructuredText files work correctly - a MyST `:link:` directive can reference an RST anchor and vice versa.
Applied to files:
docs/start/connect.md
📚 Learning: 2025-08-14T19:02:43.308Z
Learnt from: amotl
PR: crate/cratedb-guide#253
File: docs/integrate/mindsdb/index.md:21-33
Timestamp: 2025-08-14T19:02:43.308Z
Learning: In CrateDB integration documentation examples, default connection parameters (user="crate", password="", host="127.0.0.1") are intentionally used to provide working out-of-the-box examples for users with local CrateDB instances, rather than using placeholder values that require customization.
Applied to files:
docs/start/connect.md
🪛 LanguageTool
docs/start/query/ad-hoc-queries.md
[grammar] ~11-~11: There might be a mistake here.
Context: ...L queries** used for: * Troubleshooting * Exploratory analysis * Debugging systems...
(QB_NEW_EN)
[grammar] ~12-~12: There might be a mistake here.
Context: ...* Troubleshooting * Exploratory analysis * Debugging systems * Investigating anomal...
(QB_NEW_EN)
[grammar] ~13-~13: There might be a mistake here.
Context: ...Exploratory analysis * Debugging systems * Investigating anomalies * Supporting cus...
(QB_NEW_EN)
[grammar] ~14-~14: There might be a mistake here.
Context: ...ugging systems * Investigating anomalies * Supporting customer questions * Generati...
(QB_NEW_EN)
[grammar] ~15-~15: There might be a mistake here.
Context: ...nomalies * Supporting customer questions * Generating quick reports They are unpre...
(QB_NEW_EN)
[grammar] ~22-~22: There might be a mistake here.
Context: ... | | ---------------------- | -------------...
(QB_NEW_EN)
[grammar] ~23-~23: There might be a mistake here.
Context: ...-------------------------------------- | | Distributed SQL engine | Fast performa...
(QB_NEW_EN)
[grammar] ~24-~24: There might be a mistake here.
Context: ..., even on complex queries | | Real-time ingestion | Query new dat...
(QB_NEW_EN)
[grammar] ~25-~25: There might be a mistake here.
Context: ...oments after it arrives | | Flexible schemas | Combine struc...
(QB_NEW_EN)
[grammar] ~26-~26: There might be a mistake here.
Context: ...ed, JSON, text, and geospatial data | | Full SQL support | Use familiar ...
(QB_NEW_EN)
[grammar] ~27-~27: There might be a mistake here.
Context: ... for joins, filters, sorting, and more | | Easy integrations | Query from CL...
(QB_NEW_EN)
[grammar] ~110-~110: There might be a mistake here.
Context: ...-01'; ``` ## 5. Performance Tips for Ad-hoc Queries | Tip | Descr...
(QB_NEW_EN)
[grammar] ~116-~116: There might be a mistake here.
Context: ...the fields you need | | Profile queries | Use EXPLAIN a...
(QB_NEW_EN)
[grammar] ~117-~117: There might be a mistake here.
Context: ...andANALYZE` to inspect performance | | Use time filters | Especially on t...
(QB_NEW_EN)
[grammar] ~124-~124: There might be a mistake here.
Context: ... Web-based SQL editor with result viewer * PostgreSQL Clients – psql, DBeaver, Da...
(QB_NEW_EN)
[grammar] ~125-~125: There might be a mistake here.
Context: ...lients** – psql, DBeaver, DataGrip, etc. * REST API / HTTP Client – Send ad-hoc q...
(QB_NEW_EN)
[grammar] ~126-~126: There might be a mistake here.
Context: ...Client** – Send ad-hoc queries over HTTP * CrateDB Python Client – Ideal for note...
(QB_NEW_EN)
[grammar] ~127-~127: There might be a mistake here.
Context: ...t** – Ideal for notebooks and automation * Grafana / Superset – Query builder UI ...
(QB_NEW_EN)
[grammar] ~150-~150: There might be a mistake here.
Context: ...ion | | -------------------- | ---------------...
(QB_NEW_EN)
[grammar] ~151-~151: There might be a mistake here.
Context: ...-------------------------------------- | | Dynamic schemas | No need to pred...
(QB_NEW_EN)
[grammar] ~152-~152: There might be a mistake here.
Context: ...to predefine every field | | Intelligent indexing | Works out of th...
(QB_NEW_EN)
[grammar] ~153-~153: There might be a mistake here.
Context: ...t of the box for ad-hoc querying | | Time-series support | Perfect for tim...
(QB_NEW_EN)
[grammar] ~154-~154: There might be a mistake here.
Context: ...for time-bound diagnostics | | Object columns | Flexible modeli...
(QB_NEW_EN)
[grammar] ~155-~155: There might be a mistake here.
Context: ... modeling of JSON data | | Full-text & filter | Combine keyword...
(QB_NEW_EN)
[grammar] ~160-~160: There might be a mistake here.
Context: ...# 9. Learn More * CrateDB SQL Reference * CrateDB Console * Blog – How to Run Expl...
(QB_NEW_EN)
[grammar] ~162-~162: There might be a mistake here.
Context: ... * Blog – How to Run Exploratory Queries * CrateDB Academy – Querying at Scale ## ...
(QB_NEW_EN)
docs/start/first-steps.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...ickly with CrateDB. --- (first-steps)= # First steps with CrateDB :::{div} sd-te...
(QB_NEW_EN)
[grammar] ~17-~17: There might be a mistake here.
Context: ...t to deploy CrateDB yourself, select the {ref}on-premises <install> or the {ref...
(QB_NEW_EN)
[grammar] ~18-~18: There might be a mistake here.
Context: ...he {ref}cloud-provider <install-cloud> option. ## 2. Take a starter tutorial ...
(QB_NEW_EN)
[grammar] ~23-~23: There might be a mistake here.
Context: ...utorials that best match your interests, or run them interactively from the Crate...
(QB_NEW_EN)
[grammar] ~29-~29: There might be a mistake here.
Context: ...-structured data from various platforms. You will also discover how to use gene...
(QB_NEW_EN)
[style] ~31-~31: Consider a different adjective to strengthen your wording.
Context: ... columns to parse and manage URLs for deeper insights. * **Interested in full-text ...
(DEEP_PROFOUND)
docs/start/query/ai-integration.md
[grammar] ~7-~7: There might be a mistake here.
Context: ...rformance for time-series or sensor data * Real-time queries across structured and ...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ...ross structured and semi-structured data * SQL-powered transformations and filterin...
(QB_NEW_EN)
[grammar] ~9-~9: There might be a mistake here.
Context: ...QL-powered transformations and filtering * Native support for embeddings via **FLOA...
(QB_NEW_EN)
[grammar] ~82-~82: There might be a mistake here.
Context: ... | | ------------------- | ----------------...
(QB_NEW_EN)
[grammar] ~83-~83: There might be a mistake here.
Context: ...-------------------------------------- | | Feature Store | Store pre-comput...
(QB_NEW_EN)
[grammar] ~84-~84: There might be a mistake here.
Context: ...ted features with SQL access | | Real-Time Inference | Serve vector-bas...
(QB_NEW_EN)
[grammar] ~85-~85: There might be a mistake here.
Context: ...sed results with KNN_MATCH | | Experimentation | Use SQL for fast...
(QB_NEW_EN)
[grammar] ~86-~86: There might be a mistake here.
Context: ...t slicing, filtering, and aggregations | | Monitoring | Track model perf...
(QB_NEW_EN)
[grammar] ~87-~87: There might be a mistake here.
Context: ...formance, drift, or input quality | | Data Collection | Capture telemetr...
(QB_NEW_EN)
[grammar] ~131-~131: There might be a mistake here.
Context: ...ion | | -------------------- | ---------------...
(QB_NEW_EN)
[grammar] ~132-~132: There might be a mistake here.
Context: ...-------------------------------------- | | Python | crate-python ...
(QB_NEW_EN)
[grammar] ~133-~133: There might be a mistake here.
Context: ...ython` for pandas, scikit-learn | | LangChain | Native CrateDB ...
(QB_NEW_EN)
[grammar] ~134-~134: There might be a mistake here.
Context: ...rateDB vector store | | Jupyter | Ideal for exper...
(QB_NEW_EN)
[grammar] ~135-~135: There might be a mistake here.
Context: ...r experimentation, model development | | OpenAI, Cohere, etc. | Store and searc...
(QB_NEW_EN)
[grammar] ~136-~136: There might be a mistake here.
Context: ...d search their embeddings via SQL | | Kafka | Connect for rea...
(QB_NEW_EN)
[grammar] ~141-~141: There might be a mistake here.
Context: ...iption | | ------------------- | ----------------...
(QB_NEW_EN)
[grammar] ~142-~142: There might be a mistake here.
Context: ...-------------------------------------- | | FLOAT_VECTOR | High-dimensional...
(QB_NEW_EN)
[grammar] ~143-~143: There might be a mistake here.
Context: ...dimensional embedding support | | KNN_MATCH | Nearest neighbor...
(QB_NEW_EN)
[grammar] ~144-~144: There might be a mistake here.
Context: ...st neighbor search in SQL | | JSON & full-text | Store unstructur...
(QB_NEW_EN)
[grammar] ~145-~145: There might be a mistake here.
Context: ... unstructured and semi-structured data | | Joins & aggregates | Combine data in ...
(QB_NEW_EN)
[grammar] ~146-~146: There might be a mistake here.
Context: ...ne data in real-time | | Time-series support | Perfect for sens...
(QB_NEW_EN)
[grammar] ~151-~151: There might be a mistake here.
Context: ...ing & Resources** * Vector Search use case * [LangChain Integration with CrateDB](http...
(QB_NEW_EN)
[grammar] ~152-~152: There might be a mistake here.
Context: ...h) * LangChain Integration with CrateDB * [CrateDB ML Guide](https://cratedb.com/do...
(QB_NEW_EN)
[grammar] ~153-~153: There might be a mistake here.
Context: .../providers/cratedb/) * CrateDB ML Guide * [CrateDB + Embeddings Blog](https://crate...
(QB_NEW_EN)
[grammar] ~154-~154: There might be a mistake here.
Context: ...index.html) * CrateDB + Embeddings Blog * [CrateDB Examples – ML](https://github.co...
(QB_NEW_EN)
[grammar] ~155-~155: There might be a mistake here.
Context: ...rch-in-cratedb) * CrateDB Examples – ML
(QB_NEW_EN)
docs/start/going-further.md
[grammar] ~1-~1: There might be a mistake here.
Context: (start-going-further)= # Going further To learn more about Crate...
(QB_NEW_EN)
[grammar] ~4-~4: There might be a mistake here.
Context: ...invite you to explore the other sections of the documentation portal. :::::{card...
(QB_NEW_EN)
[grammar] ~9-~9: There might be a mistake here.
Context: ...ion portal. :::::{card} ::::{sd-table} :widths: 4 8 :::{sd-row} ```{sd-item} *...
(QB_NEW_EN)
docs/start/index.md
[grammar] ~1-~1: There might be a mistake here.
Context: (use)= (getting-started)= # Getting Started ``...
(QB_NEW_EN)
[grammar] ~2-~2: There might be a mistake here.
Context: (use)= (getting-started)= # Getting Started ```{toctree} :maxdepth:...
(QB_NEW_EN)
docs/start/connect.md
[grammar] ~1-~1: There might be a mistake here.
Context: (start-connect)= # Connect to CrateDB :::{include} /_inclu...
(QB_NEW_EN)
[grammar] ~4-~4: There might be a mistake here.
Context: ...CrateDB :::{include} /_include/links.md ::: Once CrateDB is {ref}`installed and...
(QB_NEW_EN)
[grammar] ~7-~7: There might be a mistake here.
Context: ...ng `, you can start to interact with the database for the first time. ...
(QB_NEW_EN)
[grammar] ~16-~16: There might be a mistake here.
Context: ...tration interface called [Admin UI]. ::: It is enabled on each CrateDB node, you ...
(QB_NEW_EN)
[grammar] ~40-~40: There might be a mistake here.
Context: ...on your favorite terminal. To learn more about it, please refer to its documentat...
(QB_NEW_EN)
[grammar] ~46-~46: There might be a mistake here.
Context: ...query.png){width=320px} {#use-dive-in} {#use-start-building} ## Adapters and dr...
(QB_NEW_EN)
[grammar] ~47-~47: There might be a mistake here.
Context: ...} {#use-dive-in} {#use-start-building} ## Adapters and drivers :::{div} - To learn...
(QB_NEW_EN)
[grammar] ~48-~48: There might be a mistake here.
Context: ...-start-building} ## Adapters and drivers :::{div} - To learn how to connect to Cr...
(QB_NEW_EN)
[grammar] ~49-~49: There might be a mistake here.
Context: ...ilding} ## Adapters and drivers :::{div} - To learn how to connect to CrateDB using...
(QB_NEW_EN)
[grammar] ~53-~53: There might be a mistake here.
Context: ...so visit the [CrateDB Reference Manual]. :::
(QB_NEW_EN)
docs/start/applications.md
[grammar] ~1-~1: There might be a mistake here.
Context: (sample-applications)= # Sample Applications ::::{grid} :::{gri...
(QB_NEW_EN)
[grammar] ~6-~6: There might be a mistake here.
Context: ...cations ::::{grid} :::{grid-item-card} 🔗 https://github.com/crate/crate-sa...
(QB_NEW_EN)
[grammar] ~7-~7: There might be a mistake here.
Context: ...tps://github.com/crate/crate-sample-apps A JavaScript guestbook app with a number...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ...er of different backend implementations, each using a different client library to...
(QB_NEW_EN)
docs/start/query/aggregations.md
[grammar] ~119-~119: There might be a mistake here.
Context: ...* COUNT(), SUM(), AVG(), MIN(), MAX() * STDDEV_POP(), VAR_POP(), PERCENTILE() * `APPROX_...
(QB_NEW_EN)
[grammar] ~122-~122: There might be a mistake here.
Context: ...ggregates**: FILTER (WHERE ...) syntax * Windowed Aggregations: via OVER(...)...
(QB_NEW_EN)
[grammar] ~139-~139: There might be a mistake here.
Context: ...dashboards with time-series aggregations * Apache Superset → Explore multidimensi...
(QB_NEW_EN)
[grammar] ~140-~140: There might be a mistake here.
Context: ...→ Explore multidimensional data visually * Tableau, Power BI, Metabase → Connect ...
(QB_NEW_EN)
docs/start/query/index.md
[grammar] ~1-~1: There might be a mistake here.
Context: (start-query)= (query-capabilities)= # Query capabiliti...
(QB_NEW_EN)
[grammar] ~2-~2: There might be a mistake here.
Context: (start-query)= (query-capabilities)= # Query capabilities ```{toctree} :maxdep...
(QB_NEW_EN)
[grammar] ~14-~14: There might be a mistake here.
Context: ...ies search ai-integration ``` :::{note} SQL is the most widely used language for...
(QB_NEW_EN)
[grammar] ~15-~15: There might be a mistake here.
Context: ...age for querying data and is the natural choice for people in many roles working ...
(QB_NEW_EN)
[grammar] ~18-~18: There might be a mistake here.
Context: ... SQL with functionalities to support its data types, data I/O procedures, and clu...
(QB_NEW_EN)
🪛 markdownlint-cli2 (0.17.2)
docs/start/first-steps.md
56-56: Link and image reference definitions should be needed
Unused link or image reference definition: "check out our support plans"
(MD053, link-image-reference-definitions)
docs/start/applications.md
7-7: Bare URL used
(MD034, no-bare-urls)
⏰ 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 (12)
docs/start/first-steps.md (1)
16-19: Cross-reference labels confirmed
Both{ref}targets are defined and will resolve correctly:
installindocs/install/index.rst(.. _install:)install-cloudindocs/install/cloud/index.rst(.. _install-cloud:)No changes required.
docs/start/query/ad-hoc-queries.md (1)
53-56: Validate geospatial example syntax for CrateDBThe example uses
within(geo_point(...), geo_polygon([...])). Please verify this matches CrateDB’s supported geo functions and data types for polygons.If needed, replace with a known-good pattern. Example alternatives (adjust to your schema):
-- If you have a geo_shape column `area` and WKT polygon SELECT id FROM vehicles WHERE within(area, 'POLYGON ((...))'); -- Or filter by distance for debugging points SELECT id, latitude, longitude FROM vehicles WHERE distance(location, 'POINT (lon lat)') < 1000;docs/start/query/index.md (3)
1-3: Good use of stable labels and clear section headingDefining both
(start-query)and(query-capabilities)gives you stable cross-reference targets. Looks good.
21-23: All reference targets verified
- Local label
(sql)=defined in docs/feature/sql/index.md:1- Local label
(advanced-querying)=defined in docs/feature/query/index.md:3- External reference
crate-reference:sqlpresent in docs/feature/sql/index.md:50No changes required here.
5-12: Toctree entries confirmed
All four child pages listed indocs/start/query/index.mdexist underdocs/start/query/. Approving the landing-page structure as-is.docs/start/index.md (3)
1-3: Nice: dual labels retained for backward compatibilityKeeping
(use)alongside(getting-started)helps preserve legacy inbound links. Good call.
24-25: ✅ Custom reference roles validatedThe
project:#featuresandinv:crate-reference:*:label#indexroles are already used elsewhere in the repo and resolve correctly. No broken links expected. Approving as is.Key occurrences:
- docs/start/index.md: lines 24–25
- docs/_include/links.md: line 19 (
[CrateDB Reference Manual]: inv:crate-reference:*:label#index)- docs/use/migrate/rockset/index.md: multiple
project:#…usages (e.g.#advanced-querying,#all-features,#hybrid-index,#sql)
5-14: All toctree entries exist and are correctly named
Verified that each referenced file in docs/start/index.md is present and properly labeled:
- docs/start/first-steps.md
- docs/start/connect.md
- docs/start/going-further.md
- docs/start/query/index.md
- docs/start/applications.md
- docs/ingest/index.md
No further changes needed.
docs/start/going-further.md (2)
29-36: LGTM: cross-ref to query capabilities uses the canonical labelThe
{ref}toquery-capabilitiesmatches the label defined in the query index. All good.
91-95: Label_administrationverifiedThe
administrationanchor is already defined in the docs:
- docs/admin/index.rst:2
.. _administration:No further changes needed.
docs/start/connect.md (2)
7-8: Ignore missing install label – label is present
The_installlabel is defined in docs/install/index.rst (line 1), and Sphinx supports cross-format{ref}lookups from MyST Markdown to RST labels. No change is needed.Likely an incorrect or invalid review comment.
39-41: No change needed: intersphinx key iscrate-crash
All existing{ref}links to the Crash CLI use thecrate-crashmapping ({ref}crate-crash:index``), and there are no{ref}links using `crash:index`. The review suggestion to switch to `crash:index` is therefore incorrect—no updates required.Likely an incorrect or invalid review comment.
|
Hi. All comments that have been handled include some sort of reaction, either 👍 or 👎. It is already a lot of clickwork to convey that to other readers, please exercise it on your own on a larger patch. At the same time, we are using those markers to keep track of what has been handled already for ourselves, otherwise we'd get lost. All direct inline comments go through the regular cycle and have been resolved afterwards. On some occasions, CodeRabbit processes reviews with huge delays, or adds another round much later, which is beyond our control. Feel free to support us by resolving every comment / conversation if you can observe it has apparently concluded. Thanks! |
| @@ -0,0 +1,56 @@ | |||
| (start-connect)= | |||
| # Connect to CrateDB | |||
There was a problem hiding this comment.
Somehow this seems to be counter to the focus on getting started with Cloud only?
Is the Admin UI useful for Cloud users?
There was a problem hiding this comment.
Hi. We've elaborated about striking a good balance over here. The page was the main ingredient of the existing section, so why not keep it until a better suggestion comes up.
|
When clicking "Ingestion" in the left menu, it's opened two places: |
Yes, we slotted in that reference to the existing section, because it could be a good idea to include it into the new section. We may be able to do it differently if it hurts too much. |
Instead of letting LLMs generate non-concise information, which might not be wrong, but does not add any value, it would have been better to think about how to highlight hands-on "what you can do" details more than talking about what _could_ be done in an abstract and non-tangible attitude. Instead of spending precious cycles first generating, then remedying AI slop, it would be more important to actually spend time on the downstream adapter implementations like mlflow-cratedb, langchain-cratedb, and many others left and right, about how to promote them better. - https://github.com/crate/mlflow-cratedb - https://github.com/crate/langchain-cratedb
Better spend time on the canonical "Advanced Querying" section instead of wrapping into "Getting Started" without so much value? - https://cratedb.com/docs/guide/feature/query/
Better spend time on the canonical "Advanced Querying" section instead of wrapping into "Getting Started" without so much value other than introducing the term "ad-hoc queries"? - https://cratedb.com/docs/guide/feature/query/
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (4)
docs/start/query/ad-hoc.md (1)
126-132: Fix geospatial example: select the GEO_POINT column, not latitude/longitudeThe WHERE clause correctly uses a GEO_POINT column (
location), but the SELECT still returnslatitude, longitude. This is inconsistent and likely invalid. Return the GEO_POINT column to match CrateDB’s geo semantics.Apply:
-SELECT id, latitude, longitude +-- Assuming `location` is a GEO_POINT column on `vehicles` +SELECT id, location FROM vehicles WHERE within( location, 'POLYGON ((-73.97 40.78, -73.95 40.78, -73.95 40.76, -73.97 40.76, -73.97 40.78))' );docs/start/query/aggregations.md (1)
214-218: Good fix on “submit queries” wordingThe new phrasing avoids “push” ambiguity in BI contexts.
docs/start/connect.md (2)
42-45: Correct intersphinx key for Crash per project themeUsing {ref}
crate-crash:indexmatches the repo’s shared intersphinx config from crate-docs-theme. No change needed.
52-56: Correct target for drivers overviewPointing to {ref}
connectkeeps this page focused and delegates driver matrices to the main Connect section.
🧹 Nitpick comments (5)
docs/start/query/ad-hoc.md (1)
226-230: Avoid putting credentials in shell history; prefer env varsUsing
-u USERNAME:PASSWORDleaks creds to shell history and process lists. Recommend env vars.-curl -sSf -u USERNAME:PASSWORD -X POST https://your.cratedb.cloud:4200/_sql \ +curl -sSf -u "$CRATEDB_USER:$CRATEDB_PASSWORD" -X POST https://your.cratedb.cloud:4200/_sql \ -H "Content-Type: application/json" \ -d '{"stmt": "SELECT timestamp, message, host FROM logs WHERE log_level = ? LIMIT 10", "args": ["error"]}'Add before the snippet (outside the code block):
- Export credentials once in your shell:
export CRATEDB_USER=... CRATEDB_PASSWORD=...docs/start/query/ai-integration.md (1)
177-179: Close DB connections; use a context managerOpen connection isn’t closed in the snippet. Wrap with a context manager to avoid leaking connections in examples.
-database = sa.create_engine(os.getenv("CRATEDB_SQLALCHEMY_URL", "crate://crate@localhost:4200")) -database.connect() +database = sa.create_engine(os.getenv("CRATEDB_SQLALCHEMY_URL", "crate://crate@localhost:4200")) +with database.connect() as _conn: + passdocs/start/query/aggregations.md (2)
71-77: Clarify that HYPERLOGLOG_DISTINCT is approximateSmall accuracy tweak: call out that HLL returns an approximate cardinality. This helps set expectations vs COUNT(DISTINCT).
CrateDB supports a rich set of **SQL92-compliant** and extended functions for aggregation, including: @@ - `STDDEV()`, `PERCENTILE()`, `VARIANCE()`, `TOPK()` -- `HYPERLOGLOG_DISTINCT()` +- `HYPERLOGLOG_DISTINCT()` (approximate distinct count) - Windowed and conditional aggregations via `OVER(...)` and `FILTER (WHERE ...)` clauses
83-151: Add minimal examples for FILTER and OVER (mentioned above, not illustrated)Since FILTER and OVER are called out, one short example each will help readers.
::::{grid} 2 @@ :::{grid-item} **Statistics:** Example using PERCENTILE for tail latency. ::: :::{grid-item} ```sql SELECT PERCENTILE(response_time, 0.95) AS p95 FROM api_logs WHERE endpoint = '/checkout';:::{
+
+:::{grid-item}
+Conditional Aggregation (FILTER)
+:::
+:::{grid-item}
+```sql
+SELECT
- COUNT(*) FILTER (WHERE status = 'error') AS errors,
- COUNT(*) AS total
+FROM logs
+WHERE timestamp >= now() - INTERVAL '1 day';
+```
+:::+:::{grid-item}
+Window Function (OVER)
+:::
+:::{grid-item}
+```sql
+SELECT
- device_id,
- AVG(temperature) OVER (PARTITION BY device_id ORDER BY timestamp
ROWS BETWEEN 6 PRECEDING AND CURRENT ROW) AS avg_last_7+FROM readings;
+```
+:::</blockquote></details> <details> <summary>docs/index.md (1)</summary><blockquote> `197-201`: **Use American English consistently (“Analyze” vs “Analyse”)** Elsewhere this page uses US English (“analyzing” Line 80). Align the card subtitle for consistency. ```diff -:link-alt: Analyse information with CrateDB +:link-alt: Analyze information with CrateDB
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (15)
docs/_include/links.md(2 hunks)docs/feature/query/index.md(1 hunks)docs/getting-started.md(0 hunks)docs/index.md(1 hunks)docs/start/application/index.md(1 hunks)docs/start/connect.md(1 hunks)docs/start/first-steps.md(1 hunks)docs/start/going-further.md(1 hunks)docs/start/index.md(1 hunks)docs/start/query/ad-hoc.md(1 hunks)docs/start/query/aggregations.md(1 hunks)docs/start/query/ai-integration.md(1 hunks)docs/start/query/index.md(1 hunks)docs/start/query/performance.md(1 hunks)docs/use/analytics/index.md(1 hunks)
💤 Files with no reviewable changes (1)
- docs/getting-started.md
🚧 Files skipped from review as they are similar to previous changes (5)
- docs/use/analytics/index.md
- docs/_include/links.md
- docs/start/index.md
- docs/start/going-further.md
- docs/start/query/index.md
🧰 Additional context used
🧠 Learnings (24)
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/index.mddocs/start/connect.mddocs/start/first-steps.md
📚 Learning: 2025-08-23T15:15:18.717Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/query/ai-integration.md:265-273
Timestamp: 2025-08-23T15:15:18.717Z
Learning: In CrateDB documentation, avoid using "data lake" terminology when describing CrateDB's role, as it can create misconceptions. Prefer "real-time analytics store" or similar terms that better reflect CrateDB's actual capabilities as a real-time analytics database.
Applied to files:
docs/start/query/ad-hoc.mddocs/start/query/ai-integration.mddocs/start/query/aggregations.md
📚 Learning: 2025-08-09T11:03:33.178Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/ingest/etl/index.md:22-23
Timestamp: 2025-08-09T11:03:33.178Z
Learning: In the CrateDB Guide documentation, MyST Markdown files can use `{ref}` directives to reference labels defined in reStructuredText files using the RST syntax `.. _label:`. This cross-format referencing between MyST and RST is supported by Sphinx.
Applied to files:
docs/start/query/ai-integration.mddocs/start/connect.mddocs/start/first-steps.mddocs/start/query/performance.md
📚 Learning: 2025-08-10T17:09:32.616Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/azure-functions/index.md:31-36
Timestamp: 2025-08-10T17:09:32.616Z
Learning: In the CrateDB Guide documentation, RST files (`.rst`) use reStructuredText anchor syntax `.. _anchor-name:` while Markdown files (`.md`) use MyST syntax `(anchor-name)=`. Cross-references between MyST Markdown and reStructuredText files work correctly - a MyST `:link:` directive can reference an RST anchor and vice versa.
Applied to files:
docs/start/query/ai-integration.mddocs/start/connect.mddocs/start/first-steps.mddocs/start/query/performance.md
📚 Learning: 2025-08-09T21:40:46.154Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/streamsets/index.md:18-21
Timestamp: 2025-08-09T21:40:46.154Z
Learning: In the CrateDB Guide documentation, reStructuredText files (`.rst`) use the RST label syntax `.. _label:` while MyST Markdown files (`.md`) use the syntax `(label)=`. Both formats are used throughout the repository and labels can be cross-referenced between them.
Applied to files:
docs/start/query/ai-integration.mddocs/start/connect.mddocs/start/first-steps.mddocs/start/query/performance.md
📚 Learning: 2025-08-26T21:28:48.272Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/query/performance.md:10-16
Timestamp: 2025-08-26T21:28:48.272Z
Learning: When reviewing Sphinx documentation that uses intersphinx references (indicated by prefixes like `crate-reference:`), these references point to external documentation and won't be found by text searches within the current repository. They are validated during the Sphinx build process, not by static analysis of the repository content.
Applied to files:
docs/start/query/ai-integration.mddocs/start/connect.mddocs/start/query/performance.md
📚 Learning: 2025-08-10T18:17:49.380Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/mysql/index.md:51-55
Timestamp: 2025-08-10T18:17:49.380Z
Learning: In the CrateDB Guide documentation, the file `docs/integrate/mysql/import-csv.rst` contains the reStructuredText label `.. _mysql-import-csv:` which can be referenced from MyST Markdown files using `:link: mysql-import-csv` with `:link-type: ref`. This is another example of cross-format referencing between MyST and RST files working correctly in Sphinx.
Applied to files:
docs/start/query/ai-integration.mddocs/start/first-steps.mddocs/start/query/performance.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/query/ai-integration.md
📚 Learning: 2025-08-10T17:59:43.508Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/grafana/index.md:37-46
Timestamp: 2025-08-10T17:59:43.508Z
Learning: When verifying cross-references in Sphinx-based documentation, search for both Markdown references (e.g., `(reference-name)=`) and reStructuredText labels (e.g., `.. _reference-name:`) across both .md and .rst files, as Sphinx supports cross-referencing between different markup formats.
Applied to files:
docs/start/query/ai-integration.mddocs/start/query/performance.md
📚 Learning: 2025-08-08T16:50:14.965Z
Learnt from: amotl
PR: crate/cratedb-guide#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
Applied to files:
docs/start/query/ai-integration.mddocs/start/connect.md
📚 Learning: 2025-08-23T20:37:34.395Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/query/performance.md:1-3
Timestamp: 2025-08-23T20:37:34.395Z
Learning: When analyzing cross-references in mixed reStructuredText/Markdown Sphinx documentation projects, check for both RST-style labels (`.. _label:`) and Markdown-style labels (`(label)=`) as they can be cross-referenced between different file formats.
Applied to files:
docs/start/query/ai-integration.mddocs/start/query/performance.md
📚 Learning: 2025-08-23T04:22:52.597Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/going-further.md:20-38
Timestamp: 2025-08-23T04:22:52.597Z
Learning: In the CrateDB Guide repository, the prefix `crate-reference:` in documentation links (like `crate-reference:index`) is an intersphinx reference that points to external content in the CrateDB Reference Manual documentation. These references are intentionally not pointing to local files within the repository.
Applied to files:
docs/start/query/ai-integration.mddocs/start/connect.mddocs/start/query/performance.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/query/ai-integration.md
📚 Learning: 2025-08-22T18:11:12.776Z
Learnt from: amotl
PR: crate/cratedb-guide#263
File: docs/integrate/kafka/docker-python.md:112-120
Timestamp: 2025-08-22T18:11:12.776Z
Learning: In documentation and tutorial repositories like cratedb-guide, code examples should prioritize simplicity, clarity, and educational value over production-ready features. Comprehensive error handling, extensive validation, and other production concerns can distract from the main learning objectives and make examples harder to follow. Review suggestions should focus on correctness and clarity rather than production hardening.
Applied to files:
docs/start/query/ai-integration.mddocs/start/connect.mddocs/start/query/aggregations.md
📚 Learning: 2025-08-24T01:31:11.965Z
Learnt from: amotl
PR: crate/cratedb-guide#266
File: docs/admin/create-user.md:23-24
Timestamp: 2025-08-24T01:31:11.965Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-crash` and `crate-reference` 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/start/connect.mddocs/start/query/performance.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/start/connect.mddocs/start/query/performance.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/connect.mddocs/start/query/performance.md
📚 Learning: 2025-08-07T23:11:09.657Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
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/start/connect.md
📚 Learning: 2025-08-07T23:11:08.311Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
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/start/connect.md
📚 Learning: 2025-08-09T11:00:03.578Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/index.md:312-316
Timestamp: 2025-08-09T11:00:03.578Z
Learning: In the CrateDB Guide documentation, locally stale references (such as `(reference-architectures)=`, `(domain)=`, and similar anchor labels) should be retained even when they appear unused within the repository, as external projects might still reference them. This ensures backward compatibility for external documentation and projects.
Applied to files:
docs/start/connect.mddocs/start/first-steps.mddocs/start/query/performance.md
📚 Learning: 2025-08-23T15:09:38.537Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/index.md:1-3
Timestamp: 2025-08-23T15:09:38.537Z
Learning: In the CrateDB Guide documentation, the `(use)=` label in `docs/start/index.md` is intentionally placed alongside `(getting-started)=` as part of the documentation architecture, even though it may appear to conflict with top-level "Use" section labeling. This is a deliberate design decision by the maintainers.
Applied to files:
docs/start/connect.mddocs/start/first-steps.mddocs/start/query/aggregations.md
📚 Learning: 2025-08-14T19:02:43.308Z
Learnt from: amotl
PR: crate/cratedb-guide#253
File: docs/integrate/mindsdb/index.md:21-33
Timestamp: 2025-08-14T19:02:43.308Z
Learning: In CrateDB integration documentation examples, default connection parameters (user="crate", password="", host="127.0.0.1") are intentionally used to provide working out-of-the-box examples for users with local CrateDB instances, rather than using placeholder values that require customization.
Applied to files:
docs/start/connect.md
📚 Learning: 2025-08-23T15:12:09.946Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/first-steps.md:23-23
Timestamp: 2025-08-23T15:12:09.946Z
Learning: In the CrateDB Guide documentation system, Jinja/Python syntax like `{{ '{}(#objects-basics)'.format(tutorial) }}` is supported and functional, even though it uses Python method calls like `.format()` and references variables like `tutorial`. This is a special capability of their documentation build system.
Applied to files:
docs/start/first-steps.md
📚 Learning: 2025-08-10T20:30:16.514Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/streamsets/index.md:36-40
Timestamp: 2025-08-10T20:30:16.514Z
Learning: In reStructuredText (.rst) files, reference labels are defined using the syntax `.. _label-name:`, while in Markdown (.md) files within Sphinx documentation, labels use the syntax `(label-name)=`. When verifying cross-references in documentation, check the file extension to determine the correct label syntax to search for.
Applied to files:
docs/start/query/performance.md
🪛 LanguageTool
docs/start/application/index.md
[grammar] ~1-~1: There might be a mistake here.
Context: (example-applications)= # Sample Applications :::{rubric} Starte...
(QB_NEW_EN)
[grammar] ~5-~5: There might be a mistake here.
Context: ...ample Applications :::{rubric} Starter ::: ::::{grid} 3 :gutter: 2 :::{grid-i...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ... :::{rubric} Starter ::: ::::{grid} 3 :gutter: 2 :::{grid-item-card} JavaScri...
(QB_NEW_EN)
[grammar] ~31-~31: There might be a mistake here.
Context: ... is in. ::: :::: :::{rubric} Advanced ::: ::::{grid} 3 :gutter: 2 :::{grid-i...
(QB_NEW_EN)
[grammar] ~34-~34: There might be a mistake here.
Context: ... :::{rubric} Advanced ::: ::::{grid} 3 :gutter: 2 :::{grid-item-card} CrateDB ...
(QB_NEW_EN)
[grammar] ~74-~74: Ensure spelling is correct
Context: ...General Transit Feed Specification) and GTFS‑RT (the extra real-time feeds for GTFS) to ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~75-~75: There might be a mistake here.
Context: ... store and analyze transit system route, trip, stop, and vehicle‑movement data st...
(QB_NEW_EN)
[grammar] ~76-~76: There might be a mistake here.
Context: ...vehicle‑movement data stored in CrateDB. ::: :::{grid-item-card} CrateDB RAG / H...
(QB_NEW_EN)
[grammar] ~83-~83: There might be a mistake here.
Context: ... techniques and data from PDF files. +++ Source data and knowledge are extracted ...
(QB_NEW_EN)
[grammar] ~84-~84: There might be a mistake here.
Context: ...om text and images inside PDF documents, then stored in CrateDB as plain text wit...
(QB_NEW_EN)
[grammar] ~85-~85: There might be a mistake here.
Context: ...a full‑text index and vector embeddings. Users can ask questions of the knowledge...
(QB_NEW_EN)
docs/start/connect.md
[grammar] ~4-~4: There might be a mistake here.
Context: ...CrateDB :::{include} /_include/links.md ::: :::{div} sd-text-muted Start intera...
(QB_NEW_EN)
docs/start/first-steps.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...ickly with CrateDB. --- (first-steps)= # First steps with CrateDB :::{div} sd-te...
(QB_NEW_EN)
[grammar] ~15-~15: There might be a mistake here.
Context: ...st way to get started with CrateDB is by [creating a free CrateDB Cloud cluster][...
(QB_NEW_EN)
[grammar] ~20-~20: There might be a mistake here.
Context: ...ive tutorials that match your interests, or run them directly in the CrateDB Clou...
(QB_NEW_EN)
[grammar] ~26-~26: There might be a mistake here.
Context: ...-structured data from various platforms. You will also discover how to use gene...
(QB_NEW_EN)
[style] ~28-~28: Consider a different adjective to strengthen your wording.
Context: ... columns to parse and manage URLs for deeper insights. * **Interested in full-text ...
(DEEP_PROFOUND)
docs/start/query/aggregations.md
[grammar] ~1-~1: There might be a mistake here.
Context: (aggregation)= (aggregations)= # Aggregations :::{div}...
(QB_NEW_EN)
[grammar] ~2-~2: There might be a mistake here.
Context: (aggregation)= (aggregations)= # Aggregations :::{div} sd-text-muted Hig...
(QB_NEW_EN)
[grammar] ~9-~9: There might be a mistake here.
Context: ...umes of data using SQL. ::: :::::{grid} :padding: 0 ::::{grid-item} :class: rub...
(QB_NEW_EN)
[grammar] ~12-~12: There might be a mistake here.
Context: ...:::::{grid} :padding: 0 ::::{grid-item} :class: rubric-slimmer :columns: auto 9 ...
(QB_NEW_EN)
[grammar] ~13-~13: There might be a mistake here.
Context: ... ::::{grid-item} :class: rubric-slimmer :columns: auto 9 9 9 :::{rubric} Introd...
(QB_NEW_EN)
[grammar] ~16-~16: There might be a mistake here.
Context: ...ns: auto 9 9 9 :::{rubric} Introduction ::: Whether you are monitoring sensor n...
(QB_NEW_EN)
[grammar] ~29-~29: There might be a mistake here.
Context: ...nefits of using CrateDB for aggregations ::: | Feature | B...
(QB_NEW_EN)
[grammar] ~42-~42: There might be a mistake here.
Context: ...t performance | :::: ::::{grid-item} :class: rubric-slim :columns: auto 3 3 3...
(QB_NEW_EN)
[grammar] ~43-~43: There might be a mistake here.
Context: ...::: ::::{grid-item} :class: rubric-slim :columns: auto 3 3 3 :::{rubric} Docume...
(QB_NEW_EN)
[grammar] ~46-~46: There might be a mistake here.
Context: ...s: auto 3 3 3 :::{rubric} Documentation ::: - {ref}crate-reference:aggregation...
(QB_NEW_EN)
[grammar] ~47-~47: There might be a mistake here.
Context: ...uto 3 3 3 :::{rubric} Documentation ::: - {ref}crate-reference:aggregation - {re...
(QB_NEW_EN)
[grammar] ~48-~48: There might be a mistake here.
Context: ...3 :::{rubric} Documentation ::: - {ref}crate-reference:aggregation - {ref}performance-select :::{rubric} I...
(QB_NEW_EN)
[grammar] ~51-~51: There might be a mistake here.
Context: ...rmance-select :::{rubric} Integrations ::: - {ref}grafana - {ref}metabase` -...
(QB_NEW_EN)
[grammar] ~52-~52: There might be a mistake here.
Context: ...ce-select :::{rubric} Integrations ::: - {ref}grafana - {ref}metabase` - {ref}...
(QB_NEW_EN)
[grammar] ~53-~53: There might be a mistake here.
Context: ...t :::{rubric} Integrations ::: - {ref}grafana - {ref}metabase - {ref}powerbi` - {ref}...
(QB_NEW_EN)
[grammar] ~54-~54: There might be a mistake here.
Context: ...ntegrations ::: - {ref}grafana - {ref}metabase - {ref}powerbi - {ref}superset - {ref}...
(QB_NEW_EN)
[grammar] ~55-~55: There might be a mistake here.
Context: ...{ref}grafana - {ref}metabase - {ref}powerbi - {ref}superset - {ref}tableau :::{ru...
(QB_NEW_EN)
[grammar] ~56-~56: There might be a mistake here.
Context: ...{ref}metabase - {ref}powerbi - {ref}superset - {ref}tableau :::{rubric} See also :::...
(QB_NEW_EN)
[grammar] ~59-~59: There might be a mistake here.
Context: ... - {ref}tableau :::{rubric} See also ::: - {ref}analytics` - [Hands-on: Aggr...
(QB_NEW_EN)
[grammar] ~60-~60: There might be a mistake here.
Context: ...{ref}tableau :::{rubric} See also ::: - {ref}analytics - [Hands-on: Aggregatin...
(QB_NEW_EN)
[grammar] ~61-~61: There might be a mistake here.
Context: ...bleau :::{rubric} See also ::: - {ref}analytics` - [Hands-on: Aggregating and Grouping Data]...
(QB_NEW_EN)
[grammar] ~62-~62: There might be a mistake here.
Context: ...[Hands-on: Aggregating and Grouping Data] - [Real-Time Analytics Primer] :::: ::::: ...
(QB_NEW_EN)
[grammar] ~63-~63: There might be a mistake here.
Context: ...ing Data] - [Real-Time Analytics Primer] :::: ::::: ## Supported Aggregation F...
(QB_NEW_EN)
[grammar] ~73-~73: There might be a mistake here.
Context: ...- COUNT(), SUM(), AVG(), MIN(), MAX() - STDDEV(), PERCENTILE(), VARIANCE(), TOPK()...
(QB_NEW_EN)
[grammar] ~85-~85: There might be a mistake here.
Context: ...ommon Aggregation Patterns ::::{grid} 2 :padding: 0 :class-row: title-slim :::{...
(QB_NEW_EN)
[grammar] ~86-~86: There might be a mistake here.
Context: ...ation Patterns ::::{grid} 2 :padding: 0 :class-row: title-slim :::{grid-item} C...
(QB_NEW_EN)
[grammar] ~89-~89: There might be a mistake here.
Context: ...0 :class-row: title-slim :::{grid-item} Count & Grouping ::: :::{grid-item} ```s...
(QB_NEW_EN)
[grammar] ~90-~90: There might be a mistake here.
Context: ...le-slim :::{grid-item} Count & Grouping ::: :::{grid-item} ```sql SELECT city, C...
(QB_NEW_EN)
[grammar] ~91-~91: There might be a mistake here.
Context: ...lim :::{grid-item} Count & Grouping ::: :::{grid-item} ```sql SELECT city, COUNT...
(QB_NEW_EN)
[grammar] ~102-~102: There might be a mistake here.
Context: ...t DESC LIMIT 10; ``` ::: :::{grid-item} Time-Based Aggregation ::: :::{grid-item...
(QB_NEW_EN)
[grammar] ~103-~103: There might be a mistake here.
Context: ...: :::{grid-item} Time-Based Aggregation ::: :::{grid-item} ```sql SELECT DATE_TR...
(QB_NEW_EN)
[grammar] ~104-~104: There might be a mistake here.
Context: ...::{grid-item} Time-Based Aggregation ::: :::{grid-item} ```sql SELECT DATE_TRUNC(...
(QB_NEW_EN)
[grammar] ~114-~114: There might be a mistake here.
Context: ...RDER BY day ASC; ``` ::: :::{grid-item} Statistical Summaries ::: :::{grid-item}...
(QB_NEW_EN)
[grammar] ~115-~115: There might be a mistake here.
Context: ...:: :::{grid-item} Statistical Summaries ::: :::{grid-item} ```sql SELECT MIN(r...
(QB_NEW_EN)
[grammar] ~116-~116: There might be a mistake here.
Context: ...:::{grid-item} Statistical Summaries ::: :::{grid-item} ```sql SELECT MIN(respo...
(QB_NEW_EN)
[grammar] ~129-~129: There might be a mistake here.
Context: ...NTERVAL '1 day'; ``` ::: :::{grid-item} Nested / Object Field Aggregation ::: ::...
(QB_NEW_EN)
[grammar] ~130-~130: There might be a mistake here.
Context: ...-item} Nested / Object Field Aggregation ::: :::{grid-item} ```sql SELECT payload...
(QB_NEW_EN)
[grammar] ~131-~131: There might be a mistake here.
Context: ...m} Nested / Object Field Aggregation ::: :::{grid-item} ```sql SELECT payload['de...
(QB_NEW_EN)
[grammar] ~143-~143: There might be a mistake here.
Context: ...e using PERCENTILE for tail latency. ::: :::{grid-item} ```sql SELECT PERCENTILE(...
(QB_NEW_EN)
[grammar] ~157-~157: There might be a mistake here.
Context: ...: ## Real-World Examples ::::{grid} 2 :padding: 0 :class-row: title-slim :::{...
(QB_NEW_EN)
[grammar] ~158-~158: There might be a mistake here.
Context: ...World Examples ::::{grid} 2 :padding: 0 :class-row: title-slim :::{grid-item} *...
(QB_NEW_EN)
[grammar] ~164-~164: There might be a mistake here.
Context: ...m thousands of devices in real time. ::: :::{grid-item} ```sql SELECT device_id, ...
(QB_NEW_EN)
[grammar] ~177-~177: There might be a mistake here.
Context: ...sions like product, region, or time. ::: :::{grid-item} ```sql SELECT product_id,...
(QB_NEW_EN)
[grammar] ~192-~192: There might be a mistake here.
Context: ...d status data of vehicles in motion. ::: :::{grid-item} ```sql SELECT status, COU...
(QB_NEW_EN)
[grammar] ~216-~216: There might be a mistake here.
Context: ...ll set of integrations, please visit the documentation at {ref}bi and {ref}`vis...
(QB_NEW_EN)
docs/start/query/performance.md
[grammar] ~1-~1: There might be a mistake here.
Context: (start-performance)= # Performance considerations :::{div} sd-...
(QB_NEW_EN)
[grammar] ~10-~10: There might be a mistake here.
Context: ... | | Avoid SELECT * | Selec...
(QB_NEW_EN)
⏰ 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 (15)
docs/feature/query/index.md (2)
116-116: LGTM on the docs nav alignmentThis aligns with the new start/query/aggregations page and the broader nav reorg.
116-116: Resolved:aggregationsreference label existsThe
(aggregations)=label is defined indocs/start/query/aggregations.md(line 2), so the{ref}cross-reference is valid and no further changes are needed.
- docs/start/query/aggregations.md:2
(aggregations)=docs/start/query/ad-hoc.md (1)
239-243: Label “search-overview” is defined and link is validThe
search-overviewlabel is declared in docs/feature/search/index.md (line 1), so the{ref}link in docs/start/query/ad-hoc.md will resolve correctly.docs/start/application/index.md (1)
1-90: Solid additions; links and descriptions read wellThe cards are concise and actionable. Clear split between Starter and Advanced is helpful for onboarding.
docs/start/first-steps.md (2)
23-23: Templated tutorial links acknowledged (intentionally supported in this docs system)Retaining the
{{ '{}(#... )'.format(tutorial) }}pattern is fine given your build supports it. No action needed.Also applies to: 30-30, 35-35, 42-42
15-17: Confirm CrateDB Cloud free-tier naming and publish limits
Before merging, please manually verify the official branding for the free tier in CrateDB Cloud and adjust the copy below with its current resource caps and inactivity policy.• File:
docs/start/first-steps.md(lines 15–17)-The fastest and easiest way to get started with CrateDB is by -[creating a free CrateDB Cloud cluster][CrateDB Cloud Console]. +The fastest and easiest way to get started with CrateDB is by +deploying a free tier (CRFREE) cluster on CrateDB Cloud][CrateDB Cloud Console].Once you’ve confirmed that “CRFREE” is indeed the official free-tier name, please also consider appending a short note such as:
The CRFREE tier provides a single-node cluster (1 vCPU, 1 GB RAM, 5 GB storage) and is suspended after 30 days of inactivity.
— updating the numbers and inactivity window to match today’s offering.
docs/start/query/ai-integration.md (2)
268-273: Good phrasing: “real-time analytics store”Thanks for avoiding “data lake”; this better reflects CrateDB’s role.
145-150: Validate LlamaIndex imports and default model for text-to-SQLPlease update the import paths and default model in docs/start/query/ai-integration.md (lines 145–150 and 160–167) as follows:
• Ollama LLM
from llama_index.llms.ollama import Ollama(pypi.org)
• OpenAI LLM
from llama_index.llms.openai import OpenAI• SQLDatabase
from llama_index.core import SQLDatabase• NLSQLTableQueryEngine
from llama_index.core.query_engine import NLSQLTableQueryEngineUse a cost-effective, context-aware default OpenAI model for text-to-SQL, e.g.:
llm = OpenAI( model=os.getenv("OPENAI_MODEL", "gpt-4.1-mini"), temperature=0.0, api_key=os.getenv("OPENAI_API_KEY"), )To ensure reproducibility, consider adding a minimal
requirements.txtsnippet (outside of code cells), for example:llama-index-core ~= X.Y.Z llama-index-llms-openai ~= X.Y.Z llama-index-llms-ollama ~= X.Y.Z SQLAlchemy ~= 2.0Apply the same updates to lines 160–167.
docs/start/query/aggregations.md (2)
46-50: Local labelperformance-selectconfirmed
- The RST label
.. _performance-select:is defined indocs/performance/selects.rst(line 1), so the{ref}link will resolve correctly.
1-3: No duplicate Sphinx labels foundVerified that the
(aggregation)and(aggregations)targets are only defined in docs/start/query/aggregations.md (lines 1–2) and do not appear elsewhere in the repository. You can safely proceed without risk of duplicate-target warnings.docs/index.md (2)
16-27: Getting Started card: ref targetCard links to {ref}
getting-started. Per prior architecture, that label lives in docs/start/index.md, so this should resolve.
310-320: toctree restructuring reads wellSwitching from getting-started to start/index and adding connect/index aligns with the new navigation.
docs/start/connect.md (2)
34-36: Nice cross-link to create-userThis note is helpful for first-time remote access to the Admin UI.
30-32: Image asset path verifiedConfirmed that
docs/_assets/img/getting-started/first-use/admin-ui.pngexists, so the/ _assets/img/getting-started/first-use/admin-ui.pngreference indocs/start/connect.md(lines 30–32) is valid. No changes required.docs/start/query/performance.md (1)
19-21: Good cross-link to the canonical Performance sectionThis inter-page ref to the RST label should resolve cleanly.
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/start/first-steps.md (1)
55-55: Remove stray literal “55” at EOF to avoid build noise/breakageThere’s an orphaned “55” character at the very end of the file; this will render as body text and may fail link-checkers or doc linters.
Apply this diff:
-55
🧹 Nitpick comments (7)
docs/start/first-steps.md (4)
15-17: Nice: updated wording to the CRFREE free tierGood call aligning with the official “CRFREE” naming and keeping the reference link. Consider adding a short tip about intended use and where to verify current limits; this helps set expectations for new users without hard-coding mutable quotas.
Suggested addition (immediately after the sentence):
deploying a free tier (CRFREE) cluster on [CrateDB Cloud][CrateDB Cloud Console]. + +```{tip} Free tier notes +The CRFREE tier is intended for exploration and testing. Limits and inactivity policies may apply; please confirm the current details in the CrateDB Cloud documentation. +```If you want me to pull in the latest official wording, I can look it up and propose exact text—just say the word and I’ll verify the current limits/name and link target.
20-22: Link the console reference for consistencyMake “CrateDB Cloud Console” a reference-style link here as well (it’s already defined at the bottom).
- or run them directly in the CrateDB Cloud Console. + or run them directly in the [CrateDB Cloud Console].
9-11: Microcopy polish in the muted straplineShortening this improves readability and matches the imperative tone used elsewhere.
-How to get started with CrateDB quickly. +Get started with CrateDB quickly.
46-47: Use fenced directive syntax for rubric (minor consistency tweak)Both colon-fenced and fenced directives work in MyST; most of this repo appears to prefer fenced style for single-line directives.
-:::{rubric} Congratulations! -::: +```{rubric} Congratulations! +```docs/start/query/ad-hoc.md (2)
121-133: Geospatial snippet: align SELECT list with GEO_POINT usage and add a type/order hintThe predicate uses within(location, …) which implies a GEO_POINT column, but the SELECT projects latitude/longitude. This is slightly confusing for newcomers.
- Prefer selecting the GEO_POINT column you filter on.
- Add a brief comment that location must be GEO_POINT and WKT uses lon lat order.
Apply this diff:
-```sql -SELECT id, latitude, longitude -FROM vehicles -WHERE within( - location, - 'POLYGON ((-73.97 40.78, -73.95 40.78, -73.95 40.76, -73.97 40.76, -73.97 40.78))' -); -``` +```sql +-- location must be a GEO_POINT; WKT coordinates are in lon lat order. +SELECT id, location +FROM vehicles +WHERE within( + location, + 'POLYGON ((-73.97 40.78, -73.95 40.78, -73.95 40.76, -73.97 40.76, -73.97 40.78))' +); +```
112-118: Handle missing JSON keys to avoid grouping by NULLIf payload['device']['os'] can be absent, the GROUP BY will accumulate NULLs. Consider COALESCE to label unknowns.
-SELECT - payload['device']['os'], - COUNT(*) AS count -FROM events -GROUP BY payload['device']['os']; +SELECT + COALESCE(payload['device']['os'], 'unknown') AS os, + COUNT(*) AS count +FROM events +GROUP BY os;docs/start/query/performance.md (1)
10-11: Tighten wording on default indexing to avoid overgeneralization“Fields are indexed by default” can be read as “everything, always”. A small tweak reduces ambiguity and sets expectations about trade-offs.
-| Leverage indexes | Important for frequently grouped or filtered fields. <br> Fields are indexed by default. | {ref}`performance-optimization` | +| Leverage indexes | Important for frequently grouped or filtered fields. <br> Many column types are indexed by default; tune or disable where appropriate. | {ref}`performance-optimization` |
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
docs/start/first-steps.md(1 hunks)docs/start/query/ad-hoc.md(1 hunks)docs/start/query/aggregations.md(1 hunks)docs/start/query/performance.md(1 hunks)
🧰 Additional context used
🧠 Learnings (17)
📚 Learning: 2025-08-23T15:15:18.717Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/query/ai-integration.md:265-273
Timestamp: 2025-08-23T15:15:18.717Z
Learning: In CrateDB documentation, avoid using "data lake" terminology when describing CrateDB's role, as it can create misconceptions. Prefer "real-time analytics store" or similar terms that better reflect CrateDB's actual capabilities as a real-time analytics database.
Applied to files:
docs/start/query/ad-hoc.mddocs/start/query/aggregations.md
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/start/first-steps.md
📚 Learning: 2025-08-23T15:09:38.537Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/index.md:1-3
Timestamp: 2025-08-23T15:09:38.537Z
Learning: In the CrateDB Guide documentation, the `(use)=` label in `docs/start/index.md` is intentionally placed alongside `(getting-started)=` as part of the documentation architecture, even though it may appear to conflict with top-level "Use" section labeling. This is a deliberate design decision by the maintainers.
Applied to files:
docs/start/first-steps.mddocs/start/query/aggregations.md
📚 Learning: 2025-08-23T15:12:09.946Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/first-steps.md:23-23
Timestamp: 2025-08-23T15:12:09.946Z
Learning: In the CrateDB Guide documentation system, Jinja/Python syntax like `{{ '{}(#objects-basics)'.format(tutorial) }}` is supported and functional, even though it uses Python method calls like `.format()` and references variables like `tutorial`. This is a special capability of their documentation build system.
Applied to files:
docs/start/first-steps.md
📚 Learning: 2025-08-10T17:09:32.616Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/azure-functions/index.md:31-36
Timestamp: 2025-08-10T17:09:32.616Z
Learning: In the CrateDB Guide documentation, RST files (`.rst`) use reStructuredText anchor syntax `.. _anchor-name:` while Markdown files (`.md`) use MyST syntax `(anchor-name)=`. Cross-references between MyST Markdown and reStructuredText files work correctly - a MyST `:link:` directive can reference an RST anchor and vice versa.
Applied to files:
docs/start/first-steps.mddocs/start/query/performance.md
📚 Learning: 2025-08-09T11:03:33.178Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/ingest/etl/index.md:22-23
Timestamp: 2025-08-09T11:03:33.178Z
Learning: In the CrateDB Guide documentation, MyST Markdown files can use `{ref}` directives to reference labels defined in reStructuredText files using the RST syntax `.. _label:`. This cross-format referencing between MyST and RST is supported by Sphinx.
Applied to files:
docs/start/first-steps.mddocs/start/query/performance.md
📚 Learning: 2025-08-09T21:40:46.154Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/streamsets/index.md:18-21
Timestamp: 2025-08-09T21:40:46.154Z
Learning: In the CrateDB Guide documentation, reStructuredText files (`.rst`) use the RST label syntax `.. _label:` while MyST Markdown files (`.md`) use the syntax `(label)=`. Both formats are used throughout the repository and labels can be cross-referenced between them.
Applied to files:
docs/start/first-steps.mddocs/start/query/performance.md
📚 Learning: 2025-08-10T18:17:49.380Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/mysql/index.md:51-55
Timestamp: 2025-08-10T18:17:49.380Z
Learning: In the CrateDB Guide documentation, the file `docs/integrate/mysql/import-csv.rst` contains the reStructuredText label `.. _mysql-import-csv:` which can be referenced from MyST Markdown files using `:link: mysql-import-csv` with `:link-type: ref`. This is another example of cross-format referencing between MyST and RST files working correctly in Sphinx.
Applied to files:
docs/start/first-steps.mddocs/start/query/performance.md
📚 Learning: 2025-08-09T11:00:03.578Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/index.md:312-316
Timestamp: 2025-08-09T11:00:03.578Z
Learning: In the CrateDB Guide documentation, locally stale references (such as `(reference-architectures)=`, `(domain)=`, and similar anchor labels) should be retained even when they appear unused within the repository, as external projects might still reference them. This ensures backward compatibility for external documentation and projects.
Applied to files:
docs/start/first-steps.mddocs/start/query/performance.md
📚 Learning: 2025-08-10T20:30:16.514Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/streamsets/index.md:36-40
Timestamp: 2025-08-10T20:30:16.514Z
Learning: In reStructuredText (.rst) files, reference labels are defined using the syntax `.. _label-name:`, while in Markdown (.md) files within Sphinx documentation, labels use the syntax `(label-name)=`. When verifying cross-references in documentation, check the file extension to determine the correct label syntax to search for.
Applied to files:
docs/start/query/performance.md
📚 Learning: 2025-08-23T20:37:34.395Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/query/performance.md:1-3
Timestamp: 2025-08-23T20:37:34.395Z
Learning: When analyzing cross-references in mixed reStructuredText/Markdown Sphinx documentation projects, check for both RST-style labels (`.. _label:`) and Markdown-style labels (`(label)=`) as they can be cross-referenced between different file formats.
Applied to files:
docs/start/query/performance.md
📚 Learning: 2025-08-10T17:59:43.508Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/grafana/index.md:37-46
Timestamp: 2025-08-10T17:59:43.508Z
Learning: When verifying cross-references in Sphinx-based documentation, search for both Markdown references (e.g., `(reference-name)=`) and reStructuredText labels (e.g., `.. _reference-name:`) across both .md and .rst files, as Sphinx supports cross-referencing between different markup formats.
Applied to files:
docs/start/query/performance.md
📚 Learning: 2025-08-26T21:28:48.295Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/query/performance.md:10-16
Timestamp: 2025-08-26T21:28:48.295Z
Learning: When reviewing Sphinx documentation that uses intersphinx references (indicated by prefixes like `crate-reference:`), these references point to external documentation and won't be found by text searches within the current repository. They are validated during the Sphinx build process, not by static analysis of the repository content.
Applied to files:
docs/start/query/performance.md
📚 Learning: 2025-08-23T04:22:52.597Z
Learnt from: amotl
PR: crate/cratedb-guide#235
File: docs/start/going-further.md:20-38
Timestamp: 2025-08-23T04:22:52.597Z
Learning: In the CrateDB Guide repository, the prefix `crate-reference:` in documentation links (like `crate-reference:index`) is an intersphinx reference that points to external content in the CrateDB Reference Manual documentation. These references are intentionally not pointing to local files within the repository.
Applied to files:
docs/start/query/performance.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/query/performance.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/start/query/performance.md
📚 Learning: 2025-08-24T01:31:11.965Z
Learnt from: amotl
PR: crate/cratedb-guide#266
File: docs/admin/create-user.md:23-24
Timestamp: 2025-08-24T01:31:11.965Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-crash` and `crate-reference` 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/start/query/performance.md
🪛 LanguageTool
docs/start/query/ad-hoc.md
[grammar] ~1-~1: There might be a mistake here.
Context: (ad-hoc-queries)= # Ad-hoc queries :::{div} sd-text-muted S...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ...le, real-time datasets. ::: :::::{grid} :padding: 0 ::::{grid-item} :class: rub...
(QB_NEW_EN)
[grammar] ~11-~11: There might be a mistake here.
Context: ...:::::{grid} :padding: 0 ::::{grid-item} :class: rubric-slimmer :columns: auto 9 ...
(QB_NEW_EN)
[grammar] ~12-~12: There might be a mistake here.
Context: ... ::::{grid-item} :class: rubric-slimmer :columns: auto 9 9 9 :::{rubric} Introd...
(QB_NEW_EN)
[grammar] ~15-~15: There might be a mistake here.
Context: ...ns: auto 9 9 9 :::{rubric} Introduction ::: Whether you're a developer, data an...
(QB_NEW_EN)
[grammar] ~22-~22: There might be a mistake here.
Context: ...e. :::{rubric} What are ad-hoc queries? ::: Ad-hoc queries are **spontaneous, o...
(QB_NEW_EN)
[grammar] ~27-~27: There might be a mistake here.
Context: ...L queries** used for: - Troubleshooting - Exploratory analysis - Debugging systems...
(QB_NEW_EN)
[grammar] ~28-~28: There might be a mistake here.
Context: ...- Troubleshooting - Exploratory analysis - Debugging systems - Investigating anomal...
(QB_NEW_EN)
[grammar] ~29-~29: There might be a mistake here.
Context: ...Exploratory analysis - Debugging systems - Investigating anomalies - Supporting cus...
(QB_NEW_EN)
[grammar] ~30-~30: There might be a mistake here.
Context: ...ugging systems - Investigating anomalies - Supporting customer questions - Generati...
(QB_NEW_EN)
[grammar] ~31-~31: There might be a mistake here.
Context: ...nomalies - Supporting customer questions - Generating quick reports They are unpre...
(QB_NEW_EN)
[grammar] ~41-~41: There might be a mistake here.
Context: ... | | ---------------------- |--------------...
(QB_NEW_EN)
[grammar] ~42-~42: There might be a mistake here.
Context: ...---------------------------------------| | Distributed SQL engine | Fast performa...
(QB_NEW_EN)
[grammar] ~43-~43: There might be a mistake here.
Context: ..., even on complex queries | | Real-time ingestion | Query new dat...
(QB_NEW_EN)
[grammar] ~44-~44: There might be a mistake here.
Context: ...oments after it arrives | | Flexible schemas | Combine struc...
(QB_NEW_EN)
[grammar] ~45-~45: There might be a mistake here.
Context: ...ed, JSON, text, and geospatial data | | Full SQL support | Use familiar ...
(QB_NEW_EN)
[grammar] ~46-~46: There might be a mistake here.
Context: ... for joins, filters, sorting, and more | | Easy integrations | Query from CL...
(QB_NEW_EN)
[grammar] ~51-~51: There might be a mistake here.
Context: ...} When to use CrateDB for ad-hoc queries ::: - Explore new patterns in operat...
(QB_NEW_EN)
[grammar] ~52-~52: There might be a mistake here.
Context: ...en to use CrateDB for ad-hoc queries ::: - Explore new patterns in operational ...
(QB_NEW_EN)
[grammar] ~62-~62: There might be a mistake here.
Context: ...es or OLAP cubes :::: ::::{grid-item} :class: rubric-slim :columns: auto 3 3 3...
(QB_NEW_EN)
[grammar] ~63-~63: There might be a mistake here.
Context: ...::: ::::{grid-item} :class: rubric-slim :columns: auto 3 3 3 :::{rubric} Relate...
(QB_NEW_EN)
[grammar] ~66-~66: There might be a mistake here.
Context: ...auto 3 3 3 :::{rubric} Related Features ::: - {ref}object - {ref}fts - {ref}...
(QB_NEW_EN)
[grammar] ~67-~67: There might be a mistake here.
Context: ... 3 3 3 :::{rubric} Related Features ::: - {ref}object - {ref}fts - {ref}`times...
(QB_NEW_EN)
[grammar] ~68-~68: There might be a mistake here.
Context: ...:::{rubric} Related Features ::: - {ref}object - {ref}fts - {ref}timeseries :::{rubr...
(QB_NEW_EN)
[grammar] ~69-~69: There might be a mistake here.
Context: ...ted Features ::: - {ref}object - {ref}fts - {ref}timeseries :::{rubric} Reference...
(QB_NEW_EN)
[grammar] ~72-~72: There might be a mistake here.
Context: ...es :::{rubric} Reference Documentation ::: - {ref}CrateDB SQL Reference <crate...
(QB_NEW_EN)
[grammar] ~73-~73: There might be a mistake here.
Context: ... :::{rubric} Reference Documentation ::: - {ref}`CrateDB SQL Reference <crate-refer...
(QB_NEW_EN)
[grammar] ~74-~74: There might be a mistake here.
Context: ...ric} Reference Documentation ::: - {ref}CrateDB SQL Reference <crate-reference:sql> - {ref}`CrateDB Console <crate-crash:index...
(QB_NEW_EN)
[grammar] ~75-~75: There might be a mistake here.
Context: ...Reference crate-reference:sql - {ref}CrateDB Console crate-crash:index - {ref}crate-reference:data-types-objects...
(QB_NEW_EN)
[grammar] ~76-~76: There might be a mistake here.
Context: ...eDB Console crate-crash:index - {ref}crate-reference:data-types-objects - {ref}crate-reference:fulltext-indices` ...
(QB_NEW_EN)
[grammar] ~79-~79: There might be a mistake here.
Context: ...ulltext-indices` :::{rubric} Learn more ::: - [Exploratory Time Series Data Anal...
(QB_NEW_EN)
[grammar] ~80-~80: There might be a mistake here.
Context: ...ext-indices` :::{rubric} Learn more ::: - [Exploratory Time Series Data Analysis] -...
(QB_NEW_EN)
[grammar] ~81-~81: There might be a mistake here.
Context: ...- [Exploratory Time Series Data Analysis] - [Academy: Time Series Query Optimization]...
(QB_NEW_EN)
[grammar] ~82-~82: There might be a mistake here.
Context: ...[Academy: Time Series Query Optimization] - [CrateDB Scalability Benchmark: Query Thr...
(QB_NEW_EN)
[grammar] ~83-~83: There might be a mistake here.
Context: ...Scalability Benchmark: Query Throughput] :::: ::::: ## Common Query Patterns ...
(QB_NEW_EN)
[grammar] ~91-~91: There might be a mistake here.
Context: ... ## Common Query Patterns ::::{grid} 2 :padding: 0 :class-row: title-slim :::{...
(QB_NEW_EN)
[grammar] ~92-~92: There might be a mistake here.
Context: ...Query Patterns ::::{grid} 2 :padding: 0 :class-row: title-slim :::{grid-item} Q...
(QB_NEW_EN)
[grammar] ~95-~95: There might be a mistake here.
Context: ...0 :class-row: title-slim :::{grid-item} Quick Filters ::: :::{grid-item} ```sql ...
(QB_NEW_EN)
[grammar] ~96-~96: There might be a mistake here.
Context: ...title-slim :::{grid-item} Quick Filters ::: :::{grid-item} ```sql SELECT timesta...
(QB_NEW_EN)
[grammar] ~97-~97: There might be a mistake here.
Context: ...e-slim :::{grid-item} Quick Filters ::: :::{grid-item} ```sql SELECT timestamp, ...
(QB_NEW_EN)
[grammar] ~108-~108: There might be a mistake here.
Context: ...p DESC LIMIT 50; ``` ::: :::{grid-item} Explore Nested JSON ::: :::{grid-item} `...
(QB_NEW_EN)
[grammar] ~109-~109: There might be a mistake here.
Context: ... ::: :::{grid-item} Explore Nested JSON ::: :::{grid-item} ```sql SELECT paylo...
(QB_NEW_EN)
[grammar] ~110-~110: There might be a mistake here.
Context: ... :::{grid-item} Explore Nested JSON ::: :::{grid-item} ```sql SELECT payload['...
(QB_NEW_EN)
[grammar] ~121-~121: There might be a mistake here.
Context: ...'device']['os']; ``` ::: :::{grid-item} Geospatial Debugging ::: :::{grid-item} ...
(QB_NEW_EN)
[grammar] ~122-~122: There might be a mistake here.
Context: ...::: :::{grid-item} Geospatial Debugging ::: :::{grid-item} ```sql SELECT id, lat...
(QB_NEW_EN)
[grammar] ~123-~123: There might be a mistake here.
Context: ... :::{grid-item} Geospatial Debugging ::: :::{grid-item} ```sql SELECT id, latitud...
(QB_NEW_EN)
[grammar] ~135-~135: There might be a mistake here.
Context: ...3.97 40.78))' ); ::: :::{grid-item} Time-bound Query ::: :::{grid-item}s...
(QB_NEW_EN)
[grammar] ~136-~136: There might be a mistake here.
Context: ...::: :::{grid-item} Time-bound Query ::: :::{grid-item}sql SELECT timesta...
(QB_NEW_EN)
[grammar] ~137-~137: There might be a mistake here.
Context: ...::: :::{grid-item} Time-bound Query ::: :::{grid-item} ```sql SELECT timestamp, ...
(QB_NEW_EN)
[grammar] ~146-~146: There might be a mistake here.
Context: ...AL '15 minutes'; ``` ::: :::{grid-item} Join Across Tables ::: :::{grid-item} ``...
(QB_NEW_EN)
[grammar] ~147-~147: There might be a mistake here.
Context: ...` ::: :::{grid-item} Join Across Tables ::: :::{grid-item} ```sql SELECT o.order...
(QB_NEW_EN)
[grammar] ~148-~148: There might be a mistake here.
Context: ...: :::{grid-item} Join Across Tables ::: :::{grid-item} ```sql SELECT o.order_id,...
(QB_NEW_EN)
[grammar] ~163-~163: There might be a mistake here.
Context: ...: ## Real-World Examples ::::{grid} 2 :padding: 0 :class-row: title-slim :::{...
(QB_NEW_EN)
[grammar] ~164-~164: There might be a mistake here.
Context: ...World Examples ::::{grid} 2 :padding: 0 :class-row: title-slim :::{grid-item} *...
(QB_NEW_EN)
[grammar] ~170-~170: There might be a mistake here.
Context: ...tering logs or telemetry on the fly. ::: :::{grid-item} ```sql SELECT message FRO...
(QB_NEW_EN)
[grammar] ~183-~183: There might be a mistake here.
Context: ...ithout waiting for prebuilt reports. ::: :::{grid-item} ```sql SELECT city, AVG(d...
(QB_NEW_EN)
[grammar] ~196-~196: There might be a mistake here.
Context: ...new product was bought after launch. ::: :::{grid-item} ```sql SELECT COUNT(*) FR...
(QB_NEW_EN)
[grammar] ~206-~206: There might be a mistake here.
Context: ...>= '2025-07-01'; ``` ::: :::{grid-item} ::: :::{grid-item} ::: :::: ## Tools ...
(QB_NEW_EN)
[grammar] ~207-~207: There might be a mistake here.
Context: ...2025-07-01'; ``` ::: :::{grid-item} ::: :::{grid-item} ::: :::: ## Tools & In...
(QB_NEW_EN)
[grammar] ~208-~208: There might be a mistake here.
Context: ...` ::: :::{grid-item} ::: :::{grid-item} ::: :::: ## Tools & Interfaces Crate...
(QB_NEW_EN)
[grammar] ~220-~220: There might be a mistake here.
Context: ...Client** – Send ad-hoc queries over HTTP - **{ref}`CrateDB Python Client <crate-pytho...
(QB_NEW_EN)
[grammar] ~221-~221: There might be a mistake here.
Context: ...`** – Ideal for notebooks and automation - Grafana / Superset – Query builder UI ...
(QB_NEW_EN)
docs/start/first-steps.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...ickly with CrateDB. --- (first-steps)= # First steps with CrateDB :::{div} sd-te...
(QB_NEW_EN)
[grammar] ~15-~15: There might be a mistake here.
Context: ...st way to get started with CrateDB is by deploying a free tier (CRFREE) cluster o...
(QB_NEW_EN)
[grammar] ~20-~20: There might be a mistake here.
Context: ...ive tutorials that match your interests, or run them directly in the CrateDB Clou...
(QB_NEW_EN)
[grammar] ~25-~25: There might be a mistake here.
Context: ... complex, nested, multi‑structured data. You'll also use generated columns to p...
(QB_NEW_EN)
[style] ~26-~26: Consider a different adjective to strengthen your wording.
Context: ...lumns to parse URLs and manage them for deeper insights. * **Interested in full-text ...
(DEEP_PROFOUND)
docs/start/query/aggregations.md
[grammar] ~1-~1: There might be a mistake here.
Context: (aggregation)= (aggregations)= # Aggregations :::{div}...
(QB_NEW_EN)
[grammar] ~2-~2: There might be a mistake here.
Context: (aggregation)= (aggregations)= # Aggregations :::{div} sd-text-muted Hig...
(QB_NEW_EN)
[grammar] ~9-~9: There might be a mistake here.
Context: ...umes of data using SQL. ::: :::::{grid} :padding: 0 ::::{grid-item} :class: rub...
(QB_NEW_EN)
[grammar] ~12-~12: There might be a mistake here.
Context: ...:::::{grid} :padding: 0 ::::{grid-item} :class: rubric-slimmer :columns: auto 9 ...
(QB_NEW_EN)
[grammar] ~13-~13: There might be a mistake here.
Context: ... ::::{grid-item} :class: rubric-slimmer :columns: auto 9 9 9 :::{rubric} Introd...
(QB_NEW_EN)
[grammar] ~16-~16: There might be a mistake here.
Context: ...ns: auto 9 9 9 :::{rubric} Introduction ::: Whether you are monitoring sensor n...
(QB_NEW_EN)
[grammar] ~29-~29: There might be a mistake here.
Context: ...nefits of using CrateDB for aggregations ::: | Feature | B...
(QB_NEW_EN)
[grammar] ~42-~42: There might be a mistake here.
Context: ...t performance | :::: ::::{grid-item} :class: rubric-slim :columns: auto 3 3 3...
(QB_NEW_EN)
[grammar] ~43-~43: There might be a mistake here.
Context: ...::: ::::{grid-item} :class: rubric-slim :columns: auto 3 3 3 :::{rubric} Docume...
(QB_NEW_EN)
[grammar] ~46-~46: There might be a mistake here.
Context: ...s: auto 3 3 3 :::{rubric} Documentation ::: - {ref}crate-reference:aggregation...
(QB_NEW_EN)
[grammar] ~47-~47: There might be a mistake here.
Context: ...uto 3 3 3 :::{rubric} Documentation ::: - {ref}crate-reference:aggregation - {re...
(QB_NEW_EN)
[grammar] ~48-~48: There might be a mistake here.
Context: ...3 :::{rubric} Documentation ::: - {ref}crate-reference:aggregation - {ref}performance-select :::{rubric} I...
(QB_NEW_EN)
[grammar] ~51-~51: There might be a mistake here.
Context: ...rmance-select :::{rubric} Integrations ::: - {ref}grafana - {ref}metabase` -...
(QB_NEW_EN)
[grammar] ~52-~52: There might be a mistake here.
Context: ...ce-select :::{rubric} Integrations ::: - {ref}grafana - {ref}metabase` - {ref}...
(QB_NEW_EN)
[grammar] ~53-~53: There might be a mistake here.
Context: ...t :::{rubric} Integrations ::: - {ref}grafana - {ref}metabase - {ref}powerbi` - {ref}...
(QB_NEW_EN)
[grammar] ~54-~54: There might be a mistake here.
Context: ...ntegrations ::: - {ref}grafana - {ref}metabase - {ref}powerbi - {ref}superset - {ref}...
(QB_NEW_EN)
[grammar] ~55-~55: There might be a mistake here.
Context: ...{ref}grafana - {ref}metabase - {ref}powerbi - {ref}superset - {ref}tableau :::{ru...
(QB_NEW_EN)
[grammar] ~56-~56: There might be a mistake here.
Context: ...{ref}metabase - {ref}powerbi - {ref}superset - {ref}tableau :::{rubric} See also :::...
(QB_NEW_EN)
[grammar] ~59-~59: There might be a mistake here.
Context: ... - {ref}tableau :::{rubric} See also ::: - {ref}analytics` - [Hands-on: Aggr...
(QB_NEW_EN)
[grammar] ~60-~60: There might be a mistake here.
Context: ...{ref}tableau :::{rubric} See also ::: - {ref}analytics - [Hands-on: Aggregatin...
(QB_NEW_EN)
[grammar] ~61-~61: There might be a mistake here.
Context: ...bleau :::{rubric} See also ::: - {ref}analytics` - [Hands-on: Aggregating and Grouping Data]...
(QB_NEW_EN)
[grammar] ~62-~62: There might be a mistake here.
Context: ...[Hands-on: Aggregating and Grouping Data] - [Real-Time Analytics Primer] :::: ::::: ...
(QB_NEW_EN)
[grammar] ~63-~63: There might be a mistake here.
Context: ...ing Data] - [Real-Time Analytics Primer] :::: ::::: ## Supported Aggregation F...
(QB_NEW_EN)
[grammar] ~73-~73: There might be a mistake here.
Context: ...- COUNT(), SUM(), AVG(), MIN(), MAX() - STDDEV(), PERCENTILE(), VARIANCE(), TOPK()...
(QB_NEW_EN)
[grammar] ~85-~85: There might be a mistake here.
Context: ...ommon Aggregation Patterns ::::{grid} 2 :padding: 0 :class-row: title-slim :::{...
(QB_NEW_EN)
[grammar] ~86-~86: There might be a mistake here.
Context: ...ation Patterns ::::{grid} 2 :padding: 0 :class-row: title-slim :::{grid-item} C...
(QB_NEW_EN)
[grammar] ~89-~89: There might be a mistake here.
Context: ...0 :class-row: title-slim :::{grid-item} Count & Grouping ::: :::{grid-item} ```s...
(QB_NEW_EN)
[grammar] ~90-~90: There might be a mistake here.
Context: ...le-slim :::{grid-item} Count & Grouping ::: :::{grid-item} ```sql SELECT city, C...
(QB_NEW_EN)
[grammar] ~91-~91: There might be a mistake here.
Context: ...lim :::{grid-item} Count & Grouping ::: :::{grid-item} ```sql SELECT city, COUNT...
(QB_NEW_EN)
[grammar] ~102-~102: There might be a mistake here.
Context: ...t DESC LIMIT 10; ``` ::: :::{grid-item} Time-Based Aggregation ::: :::{grid-item...
(QB_NEW_EN)
[grammar] ~103-~103: There might be a mistake here.
Context: ...: :::{grid-item} Time-Based Aggregation ::: :::{grid-item} ```sql SELECT DATE_TR...
(QB_NEW_EN)
[grammar] ~104-~104: There might be a mistake here.
Context: ...::{grid-item} Time-Based Aggregation ::: :::{grid-item} ```sql SELECT DATE_TRUNC(...
(QB_NEW_EN)
[grammar] ~114-~114: There might be a mistake here.
Context: ...RDER BY day ASC; ``` ::: :::{grid-item} Statistical Summaries ::: :::{grid-item}...
(QB_NEW_EN)
[grammar] ~115-~115: There might be a mistake here.
Context: ...:: :::{grid-item} Statistical Summaries ::: :::{grid-item} ```sql SELECT MIN(r...
(QB_NEW_EN)
[grammar] ~116-~116: There might be a mistake here.
Context: ...:::{grid-item} Statistical Summaries ::: :::{grid-item} ```sql SELECT MIN(respo...
(QB_NEW_EN)
[grammar] ~129-~129: There might be a mistake here.
Context: ...NTERVAL '1 day'; ``` ::: :::{grid-item} Nested / Object Field Aggregation ::: ::...
(QB_NEW_EN)
[grammar] ~130-~130: There might be a mistake here.
Context: ...-item} Nested / Object Field Aggregation ::: :::{grid-item} ```sql SELECT payload...
(QB_NEW_EN)
[grammar] ~131-~131: There might be a mistake here.
Context: ...m} Nested / Object Field Aggregation ::: :::{grid-item} ```sql SELECT payload['de...
(QB_NEW_EN)
[grammar] ~143-~143: There might be a mistake here.
Context: ...e using PERCENTILE for tail latency. ::: :::{grid-item} ```sql SELECT PERCENTILE(...
(QB_NEW_EN)
[grammar] ~157-~157: There might be a mistake here.
Context: ...: ## Real-World Examples ::::{grid} 2 :padding: 0 :class-row: title-slim :::{...
(QB_NEW_EN)
[grammar] ~158-~158: There might be a mistake here.
Context: ...World Examples ::::{grid} 2 :padding: 0 :class-row: title-slim :::{grid-item} *...
(QB_NEW_EN)
[grammar] ~164-~164: There might be a mistake here.
Context: ...m thousands of devices in real time. ::: :::{grid-item} ```sql SELECT device_id, ...
(QB_NEW_EN)
[grammar] ~177-~177: There might be a mistake here.
Context: ...sions like product, region, or time. ::: :::{grid-item} ```sql SELECT product_id,...
(QB_NEW_EN)
[grammar] ~192-~192: There might be a mistake here.
Context: ...d status data of vehicles in motion. ::: :::{grid-item} ```sql SELECT status, COU...
(QB_NEW_EN)
[grammar] ~216-~216: There might be a mistake here.
Context: ...ll set of integrations, please visit the documentation at {ref}bi and {ref}`vis...
(QB_NEW_EN)
docs/start/query/performance.md
[grammar] ~1-~1: There might be a mistake here.
Context: (start-performance)= # Performance considerations :::{div} sd-...
(QB_NEW_EN)
[grammar] ~10-~10: There might be a mistake here.
Context: ... | | Avoid SELECT * | Selec...
(QB_NEW_EN)
[grammar] ~13-~13: There might be a mistake here.
Context: ... | | Use DATE_BIN or DATE_TRUNC | Apply...
(QB_NEW_EN)
🪛 Gitleaks (8.27.2)
docs/start/query/ad-hoc.md
227-227: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
⏰ 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 (8)
docs/start/first-steps.md (1)
23-23: Acknowledged: project-specific Jinja templating for tutorial linksRetaining the
{{ '{}(#…)'.format(tutorial) }}constructs is correct for this codebase; thanks for sticking with the established pattern. No action needed.Also applies to: 28-28, 32-32, 39-39
docs/start/query/ad-hoc.md (2)
151-155: LGTM: portable date arithmeticGood use of INTERVAL syntax for portability.
237-243: Local references validated and will resolve correctlyAll four
{ref}labels used indocs/start/query/ad-hoc.mdhave matching definitions elsewhere in the guide:
- object → defined in
docs/feature/document/index.mdas(object)=- timeseries → defined in
docs/topic/timeseries/index.mdas(timeseries)=- search-overview → defined in
docs/feature/search/index.mdas(search-overview)=- fts → defined in
docs/feature/search/fts/index.mdas(fts)=These local labels will be picked up by Sphinx/MyST during the build, so no further changes are necessary.
docs/start/query/performance.md (2)
13-13: Good clarification about pre-aggregation vs. viewsCalling out that views are virtual and suggesting rollup tables is accurate and prevents a common misconception.
20-21: Cross-ref to performance is appropriate in a start pageNice pointer. Given the upstream RST label exists, this should resolve in builds.
docs/start/query/aggregations.md (3)
214-218: LGTM: clearer BI wording (“submit SQL queries”)This resolves the earlier ambiguity about “push” vs. “send/submit.”
46-50: Ref “performance-select” label verifiedThe label
performance-selectis defined at the top ofdocs/performance/selects.rst(line 1), and MyST Markdown supports cross-format{ref}directives to RST labels. This reference will resolve correctly, so no changes are needed.
71-77: Ignore function-name change suggestions—STDDEV(), VARIANCE(), TOPK(), PERCENTILE() and HYPERLOGLOG_DISTINCT() are the correct built-ins in CrateDB; there are no separate STDDEV_POP/STDDEV_SAMP or VAR_POP/VAR_SAMP variants (cratedb.com)
The existing list in docs/start/query/aggregations.md is accurate. If desired, you can add hyperlinks to each function’s reference page rather than renaming or removing entries.Likely an incorrect or invalid review comment.
| ```bash | ||
| curl -sSf -u USERNAME:PASSWORD -X POST https://your.cratedb.cloud:4200/_sql \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"stmt": "SELECT timestamp, message, host FROM logs WHERE log_level = ? LIMIT 10", "args": ["error"]}' | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Don’t hardcode credentials in docs; use env vars or .netrc
The literal USERNAME:PASSWORD pattern is routinely flagged by scanners and leads readers toward unsafe practices.
Apply this diff to use environment variables and proper quoting:
-curl -sSf -u USERNAME:PASSWORD -X POST https://your.cratedb.cloud:4200/_sql \
+curl -sSf -u "$CRATEDB_USERNAME:$CRATEDB_PASSWORD" -X POST https://your.cratedb.cloud:4200/_sql \
-H "Content-Type: application/json" \
-d '{"stmt": "SELECT timestamp, message, host FROM logs WHERE log_level = ? LIMIT 10", "args": ["error"]}'Option (outside this hunk): document a safer alternative with netrc
# ~/.netrc
machine your.cratedb.cloud login <user> password <pass>curl -sSf --netrc-file ~/.netrc -X POST https://your.cratedb.cloud:4200/_sql \
-H "Content-Type: application/json" \
-d '{"stmt":"SELECT 1"}'🧰 Tools
🪛 Gitleaks (8.27.2)
227-227: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
🤖 Prompt for AI Agents
docs/start/query/ad-hoc.md around lines 226 to 230: the example currently
hardcodes "USERNAME:PASSWORD" which encourages unsafe practices and triggers
scanners; update the curl example to use environment variables for credentials
(e.g., reference $CRATE_USER and $CRATE_PASS with proper shell quoting) and
ensure the JSON payload remains correctly quoted, and add an alternative section
showing how to use a .netrc file with --netrc-file (include the ~/.netrc format
line for machine/login/password) so readers have a secure option without
inlining credentials.
| SELECT DATE_TRUNC('day', timestamp) AS day, AVG(temperature) AS avg_temp | ||
| FROM sensor_data | ||
| GROUP BY day | ||
| ORDER BY day ASC; | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
GROUP BY alias might not be portable; prefer ordinal or repeat the expression
Many engines (including Postgres) don’t allow SELECT aliases in GROUP BY. Safer for readers:
-SELECT DATE_TRUNC('day', timestamp) AS day, AVG(temperature) AS avg_temp
-FROM sensor_data
-GROUP BY day
+SELECT DATE_TRUNC('day', timestamp) AS day, AVG(temperature) AS avg_temp
+FROM sensor_data
+GROUP BY 1
ORDER BY day ASC;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| SELECT DATE_TRUNC('day', timestamp) AS day, AVG(temperature) AS avg_temp | |
| FROM sensor_data | |
| GROUP BY day | |
| ORDER BY day ASC; | |
| ``` | |
| SELECT DATE_TRUNC('day', timestamp) AS day, AVG(temperature) AS avg_temp | |
| FROM sensor_data | |
| GROUP BY 1 | |
| ORDER BY day ASC; |
🤖 Prompt for AI Agents
In docs/start/query/aggregations.md around lines 107 to 111, the example uses
the SELECT alias "day" in the GROUP BY which is not portable across SQL engines;
change the GROUP BY to use the full expression DATE_TRUNC('day', timestamp) or
use the ordinal (1) instead, and adjust ORDER BY if necessary to also reference
the expression or ordinal to ensure portability and deterministic ordering.
About
The "getting started" section was a bit thin. This patch aims to give it more volume based on suggestions by colleagues.
Status
The patch has advanced significantly since started two weeks ago, so it is time to ship. 1
Sources
Preview
References
Footnotes
In order to ship quickly, implementing relevant comments and suggestions might be diverted to the next iteration. ↩