Improve caching policy documentation
- 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
Assessment
This issue has not been assessed yet.