App configuration options

The App builder offers several configuration options you can use to customize your app's look and behavior.

info

• Available on all pricing plans.
• Users will need Can Edit or higher project permissions to manage App configuration options.

tip

You must re-publish your App to apply any changes to App configuration options.

App display options

Use the Display options menu to optionally display a table of content in addition to any project metadata at the top of your published app.

The table of contents is automatically created based on markdown and text cell headers in your Notebook view.

• Full width: By default, Hex apps are constrained to a continuous page-like layout with a maximum width. Enabling the full width removes the maximum width, and Hex uses the width of the browser instead. Enabling this is useful for dashboard-style Hex apps.
• Table of contents: When on, a dynamic table of contents will be generated based on headings in the markdown and text cell included in the app.
• Metadata: When on, project metadata will be included as part of the app layout. Interact with the metadata preview to toggle individual fields on and off, including:
  • Name
  • Description
  • Author
  • Last edited
  • Categories
  • Status

App run settings

These settings determine when the app will run, based on different user actions. You can adjust these settings in the sidebar of the app builder, or the publish modal.

Data freshness

These settings describe what results will be shown when the an app user opens the published app:

Show results from a publish, or scheduled run (default):

The app will load faster by showing results from when the project was last published, or from a scheduled run. This is useful when:

• You do not expect the underlying data to change after being published
• A scheduled run is set up to refresh the app.
• You are embedding the app and want the app to load quickly.

The results shown on load can also be manually refreshed by anyone with Can edit permissions, via the Run and update published results button on a published app.

Note that when this setting is enabled, any interactions with the app will require the app to be rerun.

Rerun the app if stale (recommended):

When this option is enabled, upon opening a published app, viewers will either see an “Up to date” message or an icon indicating the staleness and age of the results in the upper right of the app. The exact staleness timeout is configured by the Mark app results as stale if older than time unit chosen in the project's run settings. The selected staleness timeout represents the maximum age of SQL results, as well as the maximum age of the previously computed outputs that are displayed when the app is first opened.

If an app is marked as stale when it is initially opened, Hex will automatically kick off a fresh run of the app in the background. When that run has completed, the user will be prompted to refresh the app to view the fresh results. The background run will also update the cached state of the app, so the next user who opens the app will see the most up-to-date results. The background run will never hit the cache for SQL cells, always running queries from scratch.

If the app is up to date when it is initially opened, but later becomes stale, the "Up to date" message will be replaced by the staleness icon, which app users can click on to trigger a fresh run.

Users can always click on the "Up to date" or stale icon in order to see the age of the cached results.

This setting is useful when you are using Hex to build dashboard-style reports, and want the results to be refreshed for a user regularly, without configuring a scheduled run.

Run the app from scratch:

The app will run from top to bottom when a user opens the app. This will lead to slower load times, but ensures that results are fresh.

Note that if your app relies on a SQL cell, this run may use cached SQL results to help improve run times.

SQL caching

This option will show up if the data freshness setting is set to "Show results from a publish, or scheduled run" or "Rerun from scratch".

This setting controls whether the published app leverages cached results when running queries against the warehouse. Learn more about query caching.

Stale results

This option will show up if the data freshness setting is set to "Rerun the app if stale".

This setting determines both:

• Whether the results in the app are stale, triggering a background rerun (see above)
• The maximum age of SQL results that are considered valid (see query caching for more information)

Interaction

This setting describe what happens when an app user interacts with the published app:

Automatically rerun downstream cell (default):

When an app user interacts with a published app (for example, changes an input parameter, or updates a filter cell), cells that are downstream will automatically start running.

This is useful when you want your app to respond quickly to changes in inputs.

Wait for app users to click a run button:

When an app user interacts with a published app, cells will not be run until the Run button (in the top right hand corner) is pressed. Then, the entire project will be run.

This is useful when multiple inputs should be configured before running downstream cells.