Skip to content

Index and Topics: Improve guidance #369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amotl merged 5 commits into from
Oct 6, 2025
Merged

Index and Topics: Improve guidance #369

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d387f46
Index: Improve "Solutions" section, refer to solutions and topics
amotl Oct 5, 2025
63d6f85
Topics: Refactor gallery from "Index" page into "Topics" section
amotl Oct 5, 2025
3ebf779
Topics: Improve index pages for BI, Frameworks, Datavis sections
amotl Oct 6, 2025
8834498
Topics: Implement suggestions by CodeRabbit
amotl Oct 6, 2025
c53721f
Index: Fix wording as suggested by CodeRabbit
amotl Oct 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 41 additions & 94 deletions docs/handbook/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,29 @@
(tutorials)=
(use-more-tutorials)=

# Handbook
# The CrateDB Handbook

Guides and tutorials about how to use CrateDB and CrateDB Cloud in practice.


::::{grid} 4
:padding: 0


:::{grid-item-card} Getting Started
:link: getting-started
:link-type: ref
:link-alt: Getting started with CrateDB
:padding: 1
:text-align: center
:class-card: sd-pt-3
:class-body: sd-fs-1
:class-title: sd-fs-5

{material-outlined}`rocket_launch;1.3em`
:::


:::{grid-item-card} Installation
:link: install
:link-type: ref
Expand Down Expand Up @@ -113,15 +128,15 @@ CrateDB is a distributed and scalable SQL database for storing and analyzing
massive amounts of data in near real-time, even with complex queries. It is
based on Lucene, combines a unique set of features, and is PostgreSQL-compatible.

![CrateDB feature overview diagram](https://cratedb.com/hs-fs/hubfs/nativesql.png?width=800&name=nativesql.png)
![](https://cratedb.com/hs-fs/hubfs/nativesql.png?width=800&name=nativesql.png)
Copy link

@coderabbitai coderabbitai bot Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add alt text and prefer MyST image directive for control

Current Markdown image lacks alt text and uses a remote URL with query params. Use the image directive with explicit alt/width.

Apply:

-![](https://cratedb.com/hs-fs/hubfs/nativesql.png?width=800&name=nativesql.png)
+```{image} https://cratedb.com/hs-fs/hubfs/nativesql.png
+:alt: CrateDB native SQL illustration
+:width: 800
+```
📝 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.

Suggested change
![](https://cratedb.com/hs-fs/hubfs/nativesql.png?width=800&name=nativesql.png)
🤖 Prompt for AI Agents 
In docs/handbook/index.md around line 131, replace the bare Markdown image that
uses a remote URL with query parameters with a MyST image directive that
provides alt text and explicit width; remove the query params from the URL and
use the {image} directive, adding a :alt: "CrateDB native SQL illustration" and
:width: 800 to the directive so the image is accessible and controlled by the
docs renderer.

+++
Read about all features of CrateDB at a glance.
:::


## Data ingestion

Load data into CrateDB.
Load data from many sources into CrateDB.

::::{grid} 1 2 3 3
:padding: 0
Expand Down Expand Up @@ -168,111 +183,43 @@ Load data into CrateDB.
::::


## Solutions

Learn how others are using CrateDB successfully.
## Solutions and topics

::::{grid} 1 2 3 3
::::{grid} 1 2 2 2
:margin: 4 4 0 0
:padding: 0
:gutter: 2

:::{grid-item-card} Solutions and use cases
:::{grid-item-card} {material-outlined}`lightbulb;2em` Solutions and use cases
:link: solutions
:link-type: ref
:link-alt: Solutions built with CrateDB
:padding: 1
:text-align: center
:class-card: sd-pt-3
:class-body: sd-fs-1
:class-title: sd-fs-5

{material-outlined}`lightbulb;1.3em`
:::

::::


## Topics

Learn how to apply CrateDB's features to optimally cover use-cases across different
application and topic domains, for example, by connecting CrateDB with third-party
software applications, libraries, and frameworks.

::::{grid} 1 2 3 3
:padding: 0


:::{grid-item-card} Business Intelligence
:link: bi
:link-type: ref
:link-alt: Analyse information with CrateDB
:padding: 3
:text-align: center
:class-card: sd-pt-3
:class-body: sd-fs-1
:class-title: sd-fs-5

{material-outlined}`analytics;1.3em`
:::

:::{grid-item-card} Data Visualization
:link: visualization
:link-type: ref
:link-alt: Data visualization with CrateDB
:padding: 3
:text-align: center
:class-card: sd-pt-3
:class-body: sd-fs-1
:class-title: sd-fs-5

{material-outlined}`bar_chart;1.3em`
:::


:::{grid-item-card} Machine Learning
:link: machine-learning
:link-type: ref
:link-alt: Machine Learning with CrateDB
:padding: 3
:text-align: center
:class-card: sd-pt-3
:class-body: sd-fs-1
:class-title: sd-fs-5

{material-outlined}`model_training;1.3em`
:::


:::{grid-item-card} Software Testing
:link: testing
:link-type: ref
:link-alt: Software testing with CrateDB
:padding: 3
:text-align: center
:class-card: sd-pt-3
:class-body: sd-fs-1
:class-title: sd-fs-5

{material-outlined}`integration_instructions;1.3em`
Learn about solutions built with CrateDB and
how others are using CrateDB successfully.
+++
**What's inside:**
Full-text and semantic search, real-time raw-data analytics,
industrial data, machine learning, data migrations.
:::


:::{grid-item-card} Time Series Data
:link: timeseries
:::{grid-item-card} {material-outlined}`numbers;2em` Topics
:link: topics
:link-type: ref
:link-alt: Managing Time Series Data with CrateDB
:padding: 3
:text-align: center
:class-card: sd-pt-3
:class-body: sd-fs-1
:class-title: sd-fs-5

{material-outlined}`stacked_line_chart;1.3em`
:link-alt: CrateDB topics overview
Learn how to apply CrateDB's features to optimally cover use-cases
across different application and topic domains.
For example, connect CrateDB with third-party
software applications, libraries, and frameworks.
+++
**What's inside:**
Business intelligence, data lineage, data visualization,
programming frameworks, software testing, time series data.
:::


::::



```{toctree}
:hidden:

Expand Down
1 change: 0 additions & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,4 @@ Look for the "Section A: Guide" section in the {% else %} branch.
Overview <home/index>
start/index
handbook/index

```
5 changes: 5 additions & 0 deletions docs/solution/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@
(solutions)=
# Solutions and use cases

:::{div} sd-text-muted
Learn about solutions built with CrateDB and
how others are using CrateDB successfully.
:::

CrateDB is being developed in an open-source spirit, and closely together
with its users and customers. Learn about application scenarios where CrateDB
derives many foundational features from, and how others are using CrateDB to
Expand Down
56 changes: 52 additions & 4 deletions docs/topic/bi/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,58 @@

# Business Intelligence

:::{div} sd-text-muted
CrateDB integrations with BI tools.
:::

Integrations of CrateDB with other tools, specifically related to business
analytics and intelligence software.

- {ref}`cluvio`
- {ref}`powerbi`
- {ref}`rill`
- {ref}`tableau`
:::{card} Cluvio
:link: cluvio
:link-type: ref
```{div} .float-right
![Cluvio logo](https://www.cluvio.com/images/logos/cluvio/cluvio-logo-full_color-on_light-3744dd33.svg){height=40px loading=lazy}
```
Cluvio is a cloud-based business intelligence and analytics solution
that enables businesses to analyze data through a dashboard.
```{div} .clearfix
```
:::

:::{card} Power BI
:link: powerbi
:link-type: ref
```{div} .float-right
![PowerBI logo](https://upload.wikimedia.org/wikipedia/en/thumb/2/20/Power_BI_logo.svg/192px-Power_BI_logo.svg.png?20200923233425){height=40px loading=lazy}
```
Power BI is a powerful business intelligence tool that provides a
set of data analytics and visualizations.
```{div} .clearfix
```
:::

:::{card} Rill
:link: rill
:link-type: ref
```{div} .float-right
![Rill logo](https://github.com/rilldata/rill/raw/main/docs/static/img/rill-logo-light.svg){height=40px loading=lazy}
```
Rill is an open-source operational BI framework for effortlessly
transforming data sets into powerful, opinionated dashboards using SQL.
```{div} .clearfix
```
:::

:::{card} Tableau
:link: tableau
:link-type: ref
```{div} .float-right
![Tableau logo](https://upload.wikimedia.org/wikipedia/en/thumb/0/06/Tableau_logo.svg/500px-Tableau_logo.svg.png?20200509180027){height=40px loading=lazy}
```
Tableau is a visual business intelligence and analytics software platform.
It expresses data by translating drag-and-drop actions into data queries
through an intuitive interface.
```{div} .clearfix
```
:::
89 changes: 70 additions & 19 deletions docs/topic/framework/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,81 @@
(framework)=
# Using Programming Frameworks with CrateDB
# Programming Frameworks

:::{div} sd-text-muted
Using application programming frameworks together with CrateDB.
:::

Many of them are built on top of the Python programming language, making it easy
to use the Python libraries that you know and love.
Many data-driven frameworks are built on top of the Python programming
language, making it easy to use the Python libraries that you know and love.

:::::{grid} 1 2 2 2
:margin: 4 4 0 0
:padding: 0
:gutter: 2
:::{card} Django
:link: django
:link-type: ref
```{div} .float-right
![Django logo](https://static.djangoproject.com/img/logos/django-logo-positive.svg){height=40px loading=lazy}
```
Django makes it easier to build better web apps more quickly and with less code.
```{div} .clearfix
```
:::

::::{grid-item-card} {material-outlined}`lightbulb;2em` Examples
:::{card} Gradio
:link: gradio
:link-type: ref
```{div} .float-right
![Gradio logo](https://raw.githubusercontent.com/gradio-app/gradio/main/readme_files/gradio.svg){height=40px loading=lazy}
```
Gradio is an open source programming framework for quickly creating and sharing
machine learning model demo applications, written in Python.
```{div} .clearfix
```
:::

A few quick examples about how to use selected frameworks together with CrateDB.
:::{card} Plotly
:link: plotly
:link-type: ref
```{div} .float-right
![Plotly logo](https://github.com/crate/crate-clients-tools/assets/453543/8b679c0b-2740-4dcc-88f0-1106aee7fa95){height=40px loading=lazy}
Copy link
Contributor

@bmunkholm bmunkholm Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we migrate these assets away form crate-client-tools? It's not there anymore, so I assume it's a redirect that saves this.

Copy link
Member Author

@amotl amotl Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@coderabbitai: Please create a dedicated issue about it. Thanks!

Copy link

@coderabbitai coderabbitai bot Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find all references to crate-client-tools in the repository
echo "=== Searching for crate-client-tools references ==="
rg -n "crate-client-tools" --type md -C 2

echo ""
echo "=== Counting total occurrences ==="
rg "crate-client-tools" --type md -c

Length of output: 87

🏁 Script executed:

#!/bin/bash
# Try different search patterns
echo "=== Searching for clients-tools ==="
rg -n "clients-tools" -C 2

echo ""
echo "=== Searching in docs/topic directory ==="
rg -n "github.com/crate/crate-" docs/topic/ -C 1

echo ""
echo "=== Checking the specific file ==="
cat docs/topic/framework/index.md | grep -n "github.com"

Length of output: 14871

🏁 Script executed:

#!/bin/bash
# Create a GitHub issue for migrating assets from crate-clients-tools

gh issue create \
  --title "Migrate asset references from crate-clients-tools repository" \
  --body "## Summary

The documentation currently references assets (logos, screenshots, diagrams) from the \`crate-clients-tools\` repository, which appears to no longer exist. While these references currently work (likely through redirects), we should migrate these assets to a more stable location.

## Context

This issue was raised during review of PR #369:
- PR: https://github.com/crate/cratedb-guide/pull/369
- Comment: https://github.com/crate/cratedb-guide/pull/369#discussion_r2405278279
- Raised by: @bmunkholm

## Affected Files

The following files contain references to \`github.com/crate/crate-clients-tools/assets/*\`:

### Topic Documentation (3 files, 3 references)
- \`docs/topic/visualize/index.md\` - Plotly logo
- \`docs/topic/framework/index.md\` - Plotly and Streamlit logos (2 refs)

### Integration Documentation (19 files, 37 references)
- \`docs/integrate/hop/index.md\` - Apache Hop screenshots (3 refs)
- \`docs/integrate/mindsdb/index.md\` - MindsDB logo
- \`docs/integrate/prometheus/index.md\` - Prometheus logo and architecture diagram (2 refs)
- \`docs/integrate/telegraf/index.md\` - Telegraf logo
- \`docs/integrate/superset/index.md\` - Dashboard screenshot and Preset Cloud logo (2 refs)
- \`docs/integrate/sql-server/index.md\` - Microsoft and MSSQL logos (2 refs)
- \`docs/integrate/streamlit/index.md\` - Streamlit logo
- \`docs/integrate/pyviz/index.md\` - Datashader examples (2 refs)
- \`docs/integrate/locust/tutorial.md\` - Link reference
- \`docs/integrate/pycaret/index.md\` - PyCaret logo
- \`docs/integrate/node-red/index.md\` - FlowFuse logo
- \`docs/integrate/plotly/index.md\` - Plotly logo and multiple screenshots (7 refs)
- \`docs/integrate/nifi/index.md\` - NiFi screenshots (3 refs)
- \`docs/integrate/mlflow/index.md\` - MLflow logo
- \`docs/integrate/meltano/index.md\` - Meltano logo
- \`docs/integrate/cluvio/index.md\` - Cluvio dashboard screenshots (2 refs)
- \`docs/integrate/datashader/index.md\` - Datashader examples (2 refs)
- \`docs/integrate/dask/index.md\` - Dask logo
- \`docs/connect/cli.md\` - CLI screenshots (3 refs)
- \`docs/connect/mcp/index.md\` - Discussion link

### Other (1 file)
- \`backlog.md\` - Already mentions this migration task

**Total: 23 files with 40+ asset references**

## Recommended Actions

1. Identify a suitable location for these assets (e.g., \`cratedb-guide\` repository itself, or a dedicated assets repository)
2. Download and migrate all referenced assets
3. Update all documentation files with new asset URLs
4. Verify all assets render correctly
5. Consider adding a policy for where to host documentation assets in the future

## Related

- Related to backlog item: \"Migrate all content from \`crate-clients-tools\`\"" \
  --assignee amotl \
  --repo crate/cratedb-guide

Length of output: 49

@amotl, I've created issue #371 to track the migration of assets from the crate-clients-tools repository.

The issue documents all 40+ asset references found across 23 files in the documentation, including logos, screenshots, and diagrams. I've organized them by category (topic documentation, integration documentation, etc.) and included recommended actions for the migration.

🔗 #371

🧠 Learnings used 
Learnt from: bmunkholm
PR: crate/cratedb-guide#340
File: docs/home/index.md:84-97
Timestamp: 2025-09-25T19:31:54.320Z
Learning: In the CrateDB Guide docs (MyST), the CrateDB Cloud card on the homepage should link to `getting-started` using `:link-type: ref` instead of the previous `cloud:index` intersphinx target. This change was implemented in PR #340 to direct users to the getting started section rather than directly to the Cloud documentation.

Copy link
Contributor

@bmunkholm bmunkholm Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wauu - that was a hugely effective assistance from coderabbit.
@mfussenegger you might want to take a look at how CodeRabbit - in this instance - was highly effective.

Copy link
Member Author

@amotl amotl Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it isn't an optimal example to just create an issue. There have been more valuable notes, e.g. in GH-367.

Copy link
Contributor

@bmunkholm bmunkholm Oct 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@amotl Is it the initial overview you refer to?
In the issue example, not only did it create an issue, but went beyond what asked for and found all references.

Copy link
Member Author

@amotl amotl Oct 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well ok, one could also use grep for that. I am referring to 91a87c9, where the assistant informed about deprecated features/syntax in Docker Compose before.

Copy link
Contributor

@bmunkholm bmunkholm Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh, right. That's more influential. The other is just a nice timesaver - I didn't know it could be used like that.

Copy link
Member

@mfussenegger mfussenegger Oct 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you might want to take a look at how CodeRabbit - in this instance - was highly effective.

This is something grep and sed could do several orders of magnitude cheaper.

I am referring to 91a87c9, where the assistant informed about deprecated features/syntax in Docker Compose before.

scale doesn't appear deprecated?

https://github.com/compose-spec/compose-spec/blob/main/spec.md#scale

Copy link
Member Author

@amotl amotl Oct 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah thanks. Maybe it was replicas that became deprecated and I mixed it up? I think I had a warning from Docker the other day about it. Thanks for revealing the hallucinations, we may want to turn the bot off again or just use it to convert to active voice, where it helped well the other day when bringing in larger amounts of texts.

```
Plotly Open Source Graphing Libraries make interactive, publication-quality graphs.
```{div} .clearfix
```
:::

:::{card} PyViz
:link: pyviz
:link-type: ref
```{div} .float-right
![PyViz logo](https://pyviz.org/_static/logo.png){height=40px loading=lazy}
```
The PyViz.org website is an open platform for helping users decide on the best
open-source (OSS) Python data visualization tools.
```{div} .clearfix
```
:::

:::{card} QueryZen
:link: queryzen
:link-type: ref
QueryZen makes it easier to manage SQL query statements over HTTP.
:::

:::{card} Streamlit
:link: streamlit
:link-type: ref
```{div} .float-right
![Streamlit logo](https://github.com/crate/crate-clients-tools/assets/453543/0fffb2d4-1d17-49c9-96e3-fd6ae42a39c4){height=40px loading=lazy}
```
Streamlit is an open-source application programming framework for quickly sketching
out Python data applications. It provides fast, interactive prototyping, and live editing.
```{div} .clearfix
```
:::

:::{card} {material-outlined}`lightbulb;2em` Examples
:width: 50%
A few quick examples about how to use selected frameworks together with CrateDB.
- [cratedb-examples/framework](https://github.com/crate/cratedb-examples/tree/main/framework)
+++
{tag-info}`dbt` {tag-info}`dlt` {tag-info}`Flink` {tag-info}`Gradio` {tag-info}`Graphene` {tag-info}`MCP` {tag-info}`QueryZen` {tag-info}`records` {tag-info}`Streamlit`
::::

:::::

- {ref}`django`
- {ref}`gradio`
- {ref}`plotly`
- {ref}`pyviz`
- {ref}`queryzen`
- {ref}`streamlit`
:::
Loading