cube-js / cube-js/cube

Improve caching policy documentation

Open
#1,832 3 comments 0 reactions 2 assignees Claimed by @hassankhan View on GitHub
docs
Dominant language
Rust
Stars
20.8k
Forks
2.1k
Avg merge
1d 2h
Merged PRs (30d)
181

Description

**Is your feature request related to a problem? Please describe.**

Yesterday I was met with a `"message":"Slow Query Warning",` which resulted in Cube.js querying from cache only, as shown by the message `Query is too slow to be renewed during the user request and was served from the cache. Please consider using low latency pre-aggregations.`, which was not an issue I faced in development. After consulting the docs, I didn't feel like this was explicitly stated as a behaviour in the [Caching documentation](https://cube.dev/docs/caching).

**Describe the solution you'd like**

My proposition is that caching policy should be more thoroughly documented in a way that clearly states how Cube.js handles different cases. An example of a table of content for this topic would be the following:

```
Caching
In-memory Cache
Refresh Keys
Default Refresh Keys
...
Caching Policy
Development vs Production
How to reproduce production behaviour
Caching Modes
Slow Queries
...
```

More specifically I want to know the following points:

1. What are the different scenarios that creates different caching behaviours/fallback for Cube.js?
2. If Cube.js is treated as a black box, how can I make caching deterministic?
3. What is the default rule of thumb for the refresh queries? What does Cube.js look for in general for refresh cues?

And generally, I think the most important point for a documentation is:

How can a documentation be structured in a way that I feel that I know all of the important aspects of the technology and how to maximize its potential and avoid its pitfalls?

**Describe alternatives you've considered**

Follow more closely the Community Calls, announcements & roadmaps.
If that's the recommendation, I'll do it. But I feel like this is something that should not be expected of a normal user (given that I've never done that for other common tools).

**Additional context**
I believe @hassankhan is the person to tag for docs related issues.

I have not seen your Community Calls or Roadmap, so I may be saying things that are already said. If so, sorry 🙏 😅

Also, as a general thing I think the documentation would **greatly** benefit from having an auto-generated table of content on each page that is longer than a screen + potentially a documentation site map. I think [Read The Docs](https://readthedocs.org/) has a great approach in that regards (see [PostgREST docs](https://postgrest.org/en/v7.0.0/api.html) and [NetworkX python package](https://networkx.org/documentation/stable/reference/index.html) for examples). If you agree with this approach to documentation navigability, I can create another issue specifically for this.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.