Install
Check the requirements first. The commands run on your machine with the
Databricks CLI authenticated against the workspace; -p <profile> selects the CLI profile. To
install without the CLI, see Install from the Databricks UI.
1. Get the code
git clone https://github.com/databrickslabs/impulse.git
cd impulse/apps/adhoc-reporting
Use main or check out a release tag (git checkout vX.Y.Z). Either way, impulse.lock pins the
Impulse release that report jobs install.
2. Deploy
databricks apps deploy --var warehouse_id=<warehouse id> -p <profile>
The command creates the app with its SQL warehouse, user authorization scopes and permissions,
uploads the code, starts the app and prints its URL. Run it again to update the app. The warehouse
id is shown on the warehouse's page in the workspace and by databricks warehouses list -p <profile>.
The bundle has these variables:
| Variable | Default | Meaning |
|---|---|---|
warehouse_id | required | SQL warehouse the app runs user queries on |
app_name | impulse-app | Name of the app, part of its URL |
end_user_group | users | Group that gets CAN_USE on the app |
If the workspace only allows app deployments from Git, add -t github to the command, also for
later updates. The app then deploys the checked-out commit from GitHub instead of the uploaded
folder, so that commit must be in github.com/databrickslabs/impulse, for example a release tag. To
switch an app that was deployed without -t github, first run
databricks bundle deployment bind impulse_app <app name> -t github --var warehouse_id=<warehouse id> -p <profile>.
3. Grant the service principal access
Report jobs run as the app's service principal. A catalog or schema owner grants it access once per silver and gold schema:
GRANT USE CATALOG ON CATALOG <catalog> TO `<service principal application id>`;
GRANT USE SCHEMA, SELECT ON SCHEMA <catalog>.<silver schema> TO `<service principal application id>`;
GRANT USE SCHEMA, SELECT, MODIFY, CREATE TABLE ON SCHEMA <catalog>.<gold schema> TO `<service principal application id>`;
The application id is the service_principal_client_id in the output of
databricks apps get impulse-app -p <profile>. You can also skip this step and grant from the app:
before each run, the Review & run step checks the access of both the user and the service
principal. When the service principal lacks access, the step shows the exact statements to copy,
and Grant and run runs them as the signed-in user, if that user may grant them.
Install from the Databricks UI
Without Git and the CLI, create the app from GitHub in the workspace:
- Open Databricks Apps from the app switcher, click Create app and Create a custom app,
and enter a name, for example
impulse-app. - Under Configure Git repository, enter
https://github.com/databrickslabs/impulsewith the provider GitHub, a release tag with the reference type Tag, and the source code pathapps/adhoc-reporting. Click Next: Configure; Create app on this page skips the next step. - Under Configure, add the resource SQL warehouse with the permission Can use and keep
its resource key
sql-warehouse. Add the user authorization scopessql,workspace.workspace,model-serving,catalog.catalogs:read,catalog.schemas:readandcatalog.tables:read. - Click Create app. The app deploys as soon as its compute is running.
- Click Share and give the group
usersCan use.
Then grant the service principal access as in step 3. Keep managing an app installed this way in the UI; the deploy command manages only apps it created.
Serverless without GitHub access
Report jobs install the Impulse wheel pinned in impulse.lock from its GitHub release. If
serverless compute can't reach GitHub, upload that wheel to a Unity Catalog volume, grant the app's
service principal READ VOLUME on the volume (and USE CATALOG and USE SCHEMA on its catalog
and schema), and add its path to impulse.lock before deploying:
wheel_override = "/Volumes/<catalog>/<schema>/<volume>/databricks_impulse-<version>-py3-none-any.whl"
The wheel's dependencies still come from PyPI or the workspace's package repository. Upload the
new wheel and update the path with each upgrade. This needs the deploy command without -t github:
deployments from GitHub, including those from the UI, use the unchanged impulse.lock.
Data model
Schemas in the Impulse layout need no configuration. Otherwise an admin edits the shared data model
on the app's Data model page; it's stored in /Workspace/Shared/Impulse/config.yaml. List only
the settings that differ, for example:
silver_catalog: main
silver_schema: measurements
tables:
channels: channel_data
uut:
key: uut_id
solver_config:
container_metrics:
column_name_mapping:
measurement_id: container_id
solver_config is passed to the Impulse query engine unchanged (see
Configuration). The page lists every setting with its default and
meaning, and tests the configuration against a schema with the admin's permissions before saving.
Upgrade
Pull the new version or check out a newer release tag and run the deploy command again. For an app
installed from the UI, open the menu next to Deploy on the app's page, choose Deploy using a
different source, and deploy the new tag from Git with the source code path
apps/adhoc-reporting. Reports are stored in each user's workspace folder and keep working; each
report job uses the Impulse version pinned by the deployed app.