first draft

0xBoxer · 0xBoxer · commit a532a8952308 · 2023-07-25T14:48:54.000+02:00
diff --git a/docs/app/dashboards.md b/docs/app/dashboards.md
@@ -10,8 +10,6 @@ You can freely resize every widget to match the layout you want to create.
 
 ## Creating a Dashboard
 
-
-
 <div style="position: relative; padding-bottom: calc(66.66666666666666% + 41px); height: 0;"><iframe src="https://demo.arcade.software/xTAXmlo0nCL0FOn38hW9?embed" frameborder="0" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;color-scheme: light;" title="Creating a dashboard"></iframe></div>
 
 
@@ -50,14 +48,15 @@ You can add text widgets to your dashboard.
 
 Text widgets support a subset of Markdown. You can manipulate text and embed images and GIFs.
 
-### Embedding Images and GIFs
+## Embedding Images and GIFs
 
-Our text boxes can also be used to embed images or GIFs into your Dashboard.
+Text boxes can also be used to embed images or GIFs into your Dashboard.
 
 The Syntax for embedding images is:
 
-| [Image](https://www.markdownguide.org/basic-syntax/#images-1) | `![alt text](image url)` |
-| ------------------------------------------------------------- | ------------------------ |
+``` markdown
+![alt text](image url)
+```
 
 Since you can't store images locally on our servers, you need to upload your images somewhere else or find the raw file somewhere on the internet.
 
@@ -70,3 +69,24 @@ In practice this might look like this:
 You can resize the image by simply resizing the widget it is contained in.
 
 You can combine images and text in one widget.
+
+## Keeping your Dashboard up to date
+
+Dashboards on Dune are not updated automatically. You can refresh your Dashboard by clicking on the "Run" button in the top right corner.
+
+Alternatively, you can schedule your Dashboard to be refreshed in regular intervals. 
+
+<div style="position: relative; padding-bottom: calc(63.83333333333333% + 41px); height: 0; width: 100%"><iframe src="https://demo.arcade.software/doDebCcmeiVj5xKiq4nK?embed" frameborder="0" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;color-scheme: light;" title="Meta Monitoring"></iframe></div>
+
+To schedule a dashboard:
+
+1. Click on the "clock" icon in the top right corner
+2. Select the frequency you want your Dashboard to be refreshed
+3. Select the execution tier you want to use
+4. Click on "Save"
+
+You can also schedule individual queries to be refreshed. This is useful if you have a Dashboard with many queries and only want to refresh a few of them. Learn more about scheduling queries [here](/query-editor/query-scheduler.md).
+
+## Sharing your Dashboard
+
+You can share your public Dashboard by simply sharing the URL. For private dashboards, viewers need to be part of the same team as the team that owns the Dashboard. Alternatively, you can also share your Dashboard with individual users via the "Share" button in the top right corner.
diff --git a/docs/app/query-editor/query-scheduler.md b/docs/app/query-editor/query-scheduler.md
@@ -44,12 +44,8 @@ Before we dive into the details, let's first take a look at when queries are exe
 
 - **Interactive executions** are manually triggered by a user clicking the "Run" button in the query editor page or refreshing an entire dashboard. Interactive executions can be routed via the community, medium, or large cluster, depending on the query engine selected.  
 
-- **Automatic executions** are triggered whenever any user on Dune encounters a widget on a dashboard and the widget's underlying query results are "expired". As of now, query results are set to expire every 6 hours, although this is subject to change. These automatic executions are always routed via the community cluster.
-
 - **Scheduled executions** are triggered at a specific time and frequency. Scheduled executions can be routed via the medium or large cluster, depending on the execution tier selected.
 
-
-
 #### 1. Increase the execution frequency of your queries
 
 To bypass the usual 6-hour expiration time of query results, you can schedule your queries to run at a higher frequency. This will ensure that your dashboard displays the most up-to-date data. 
@@ -60,12 +56,6 @@ All automatic query executions are routed via the community cluster. This can le
 
 If you schedule your queries instead of relying on automatic executions, you can choose a higher execution tier, which will ensure that your queries are executed reliably and in a timely manner.
 
-### Additional Info
-➕ We plan to extend the functionality of query scheduling with webhooks, alerts, and the ability to update materialized views. We are also working on a allowing you to schedule a whole dashboard at once. Stay tuned for updates!
-
-💭 Have an idea for additional features for scheduled queries? Please [submit them here](https://feedback.dune.com/)! We value your input and are regularly implementing improvements based on user feedback.
-
-
-### dashboard schedule arcade
+### Scheduling entire dashboards
 
-<div style="position: relative; padding-bottom: calc(63.83333333333333% + 41px); height: 0; width: 100%"><iframe src="https://demo.arcade.software/doDebCcmeiVj5xKiq4nK?embed" frameborder="0" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;color-scheme: light;" title="Meta Monitoring"></iframe></div>
+Instead of scheduling individual queries, you can also schedule entire dashboards. Learn more about scheduling dashboards [here](/app/dashboards.md#keeping-your-dashboard-up-to-date).
diff --git a/docs/query/.pages b/docs/query/.pages
@@ -1,5 +1,6 @@
 nav:
 - index.md
+- query-executions.md
 - DuneSQL: DuneSQL-reference
 - Writing efficient Queries: writing-efficient-queries.md
 - Querying a query: query-a-query.md
diff --git a/docs/query/query-executions.md b/docs/query/query-executions.md
@@ -0,0 +1,79 @@
+---
+title: Executions
+description: When and how do queries on Dune get executed?
+---
+
+# Overview
+
+**Queries on Dune need to be triggered and will be executed on one of our query engines.**
+
+Query executions can be triggered by any user/team in Dune for public queries and by the owner of the query for private queries. Query executions can be triggered through the query editor, the dashboard editor, or via the API. We also automatically refresh popular dashboards automatically in regular intervals. 
+
+The query engine determines the amount of resources allocated to your query. The larger the query engine, the more resources are allocated to your query. This means that queries executed on a larger query engine will run faster and are less likely to time out.
+
+## Query executions triggers
+
+Query executions on Dune are triggered in four ways:
+
+1. **Interactive executions** are manually triggered by a user clicking the "Run" button in the query editor page or refreshing an entire dashboard. Interactive executions can be routed via the community, medium, or large cluster, depending on the query engine selected.
+
+2. **Scheduled executions** are triggered at a specific time and frequency. Scheduled executions can be routed via the medium or large cluster, depending on the execution tier selected.
+
+3. **API executions** are triggered by an API call. API executions can be routed via the community, medium, or large cluster, depending on the query engine selected.
+
+4. **Popular dashboards** are automatically refreshed based on their popularity. We measure popularity based on the number of views a dashboard has received. The most popular dashboards are refreshed every 30 minutes, the least popular dashboards are refreshed every 6 hours. Popular dashboards are refreshed via the community cluster.
+
+
+<div class="cards grid" markdown>
+
+-   #### Interactive executions
+
+    ---
+
+    Trigger: user clicks "Run" button in query editor or refreshes dashboard
+
+    [→ Interactive executions](../app/query-editor/query-window.md)
+
+-  #### Scheduled executions
+
+    ---
+
+    Trigger: scheduled dashboard or query
+
+    [→ Scheduled executions](../app/query-editor/query-scheduler.md)
+
+- #### API executions
+
+    ---
+
+    Trigger: API call
+
+    [→ API executions](../api/api-reference/execute-queries/index.md)
+
+- #### Popular dashboards
+
+    ---
+
+    Trigger: Dashboard popularity
+
+
+</div>
+
+
+## Query engine size
+
+Dune has three query engine sizes: community, medium, and large. The query engine size determines the amount of resources allocated to your query. The larger the query engine, the more resources are allocated to your query. This means that queries executed on a larger query engine will run faster and are less likely to time out.
+
+### Community engine
+
+The community engine is the default query engine for all queries on Dune. It is a shared cluster, meaning that it is used by all Dune users. This means that the community cluster can be busy at times, which can lead to long loading times for the viewer if the query is resource-intensive. In the worst case, the query may even time out.
+
+### Medium engine
+
+The medium engine is built to handle most queries on Dune. It is cheap, reliable and fast. The medium engine will scale up and down depening on the demand. In contrast to the community engine, that means that running a query on the medium engine will not be affected by other users' queries.
+
+### Large engine
+
+The large engine is built to handle the most resource-intensive queries on Dune. It's blazing fast, reliable and can easily deal with large amounts of data. The large engine also scales up and down depending on the demand. Running a query on the large engine will not be affected by other users' queries.   
+In addition to that, the large engine is also the only engine that can handle queries that requires lots of planning time. This mostly happens when you query a large amount of data, when you use a lot of joins or large aggregate window functions.
+
