Databricks Metric Views

​

Before you start

• Configure a Databricks data source and deploy static Cube YAML with public views. This workflow reads the latest successful deployed build, not unsaved IDE changes.
• If a Cube source uses a two-part schema.table name, set CUBEJS_DB_DATABRICKS_CATALOG for that data source so Preview can resolve its catalog. Without it, those views are blocked.
• Ask your Databricks administrator for a dedicated target catalog and schema for the published Metric Views. The identity configured on the Cube data source needs CAN USE on its SQL warehouse, USE CATALOG and USE SCHEMA on the target and source namespaces, SELECT on source relations, and CREATE TABLE on the target schema. The same identity must own any existing Cube-managed Metric View it needs to update. It owns the temporary views it creates for the access test. See the Databricks Metric View prerequisites and Metric View ownership guidance (AWS documentation; use the equivalent pages for Azure or Google Cloud).
• Arrange target access for Databricks consumers separately. Publishing an object does not grant them SELECT on it or access to its catalog and schema.
• Databricks evaluates access to the published object under Unity Catalog permissions, not Cube’s query-time authorization. A view with a Cube access policy, or one that references a cube with an access policy, is blocked from publication; Cube access policies are never transferred to Databricks. Review the Preview result and configure Databricks grants before exposing a target to consumers.
• Cube uses the data source credential server-side; you do not enter a second token in the browser. Preview returns generated YAML to authorized users for review.

​

Publish a view

• The name pattern supports literals, ^, $, a bare . that matches any single character, and at most one .* wildcard. It is not a general regular expression and is limited to 128 characters. Review the matched views in Preview before syncing.
• Each preview or sync resolves at most 128 views per data source, whether the scope is all, selected, or pattern. If all or pattern resolves more, preview and sync reject the request; narrow the scope and try again.
• A newly deployed view enters an all or matching pattern scope on the next manual sync. A selected scope changes only when you edit it.
• Renaming a view or target creates a new target and leaves the old one retained.
• Per-view target-name and root-source overrides are available through the configuration API, but are not editable in the card.

​

Trigger publication from CI

set -euo pipefail

integration="$CUBE_API_URL/api/v1/deployments/$DEPLOYMENT_ID/databricks-metric-view-integrations/default"
auth_header="Authorization: Bearer $CUBE_API_TOKEN"
: "${SYNC_IDEMPOTENCY_KEY:?Set a unique UUID for this publication attempt}"
settings=$(curl --fail --silent --show-error --connect-timeout 10 --max-time 30 \
  -H "$auth_header" "$integration")
if ! jq -e '.configuration.enabled == true and .configuration.selectionMode == "all" and .configuration.deletionPolicy == "retain"' <<<"$settings" >/dev/null; then
  echo 'Enable publication with All views and retain before running CI.' >&2
  exit 1
fi
version=$(jq -r '.configurationVersion' <<<"$settings")

start=$(jq -n --argjson version "$version" --arg key "$SYNC_IDEMPOTENCY_KEY" \
    '{configurationVersion: $version, idempotencyKey: $key}' |
  curl --fail --silent --show-error --connect-timeout 10 --max-time 30 -X POST -H "$auth_header" \
    -H 'Content-Type: application/json' --data-binary @- "$integration/syncs")
status_url=$(jq -r '.statusUrl' <<<"$start")
if [[ -n "${EXPECTED_BUILD_JOB_ID:-}" ]]; then
  if ! jq -e --argjson expected "$EXPECTED_BUILD_JOB_ID" '.buildJobId == $expected' <<<"$start" >/dev/null; then
    jq '{runId, buildJobId, commit, statusUrl}' <<<"$start" >&2
    echo 'Run started against a different build; inspect or cancel it before retrying.' >&2
    exit 1
  fi
fi

max_polls=${MAX_POLLS:-180}
[[ "$max_polls" =~ ^[1-9][0-9]*$ ]] || { echo 'MAX_POLLS must be a positive integer.' >&2; exit 1; }
for ((attempt=0; attempt<max_polls; attempt++)); do
  run=''
  response=$(curl --silent --show-error --connect-timeout 10 --max-time 30 \
    --write-out '\n%{http_code}' \
    -H "$auth_header" "$CUBE_API_URL$status_url") || response=$'\n000'
  http_code=${response##*$'\n'}
  case "$http_code" in
    200) run=${response%$'\n'*} ;;
    000|429|5??)
      echo "Status poll returned HTTP $http_code; retrying $CUBE_API_URL$status_url" >&2
      sleep 10
      continue ;;
    *) echo "Status poll returned HTTP $http_code: $CUBE_API_URL$status_url" >&2; exit 1 ;;
  esac
  case "$(jq -r '.status' <<<"$run")" in
    QUEUED|RUNNING|CANCELLING) sleep 10 ;;
    *) break ;;
  esac
done

if [[ -z "$run" ]]; then
  echo "Last status poll returned HTTP $http_code after $max_polls attempts: $CUBE_API_URL$status_url" >&2
  exit 1
fi
case "$(jq -r '.status' <<<"$run")" in
  QUEUED|RUNNING|CANCELLING)
    echo "No terminal run status observed after $max_polls attempts: $CUBE_API_URL$status_url" >&2
    exit 1 ;;
esac

if ! jq -e '.status == "COMPLETED" and .incompleteViewCount == 0 and
  (.viewNames | length > 0) and
  (.views | length > 0) and
  all(.views[]; .outcome == "created" or .outcome == "updated" or
    .outcome == "unchanged" or .outcome == "retained_obsolete")' \
  <<<"$run" >/dev/null; then
  jq '{status, buildJobId, commit, incompleteViewCount, viewNames, views}' <<<"$run" >&2
  exit 1
fi

​

What can be published

• Supported — a static view with a clear root source and representable dimensions, measures, and joins. Review the generated YAML, then test access and sync.
• Warning — behavior-neutral metadata Databricks cannot represent, or a fan-out-unsafe measure withheld as CUBE_MEMBER_WITHHELD. Review the exact difference before accepting publication; for a withheld measure, publish it from a view rooted at its own cube.

• Dynamic JavaScript, TypeScript, or Jinja models, or unflattened extends: use static YAML and flatten inherited definitions before publishing.
• A Cube access policy on the view or a referenced cube: keep that governed view in Cube; the policy cannot be transferred to a Databricks Metric View.
• Mixed data sources or an ambiguous root dataset: use one data source and a clear root.
• A two-part schema.table source without CUBEJS_DB_DATABRICKS_CATALOG: set that variable for the selected Databricks data source and preview again.
• Non-equality, cyclic, or one-to-many joins: simplify the join. For CUBE_VIEW_JOIN_NOT_REPRESENTABLE, root the view at the many-side cube.
• Unsupported expressions or types, or multi-stage, window, or ranking calculations: simplify the model or keep that view in Cube.

​

Ownership, failures, and rollback