sql_visualization.md

subcategory
Databricks SQL

databricks_sql_visualization Resource

To manage SQLA resources you must have databricks_sql_access on your databricks_group or databricks_user.

-> documentation for this resource is a work in progress.

A visualization is always tied to a query. Every query may have one or more visualizations.

Example Usage

resource "databricks_sql_visualization" "q1v1" {
  query_id    = databricks_sql_query.q1.id
  type        = "table"
  name        = "My Table"
  description = "Some Description"

  // The options encoded in this field are passed verbatim to the SQLA API.
  options = jsonencode(
    {
      "itemsPerPage" : 25,
      "columns" : [
        {
          "name" : "p1",
          "type" : "string"
          "title" : "Parameter 1",
          "displayAs" : "string",
        },
        {
          "name" : "p2",
          "type" : "string"
          "title" : "Parameter 2",
          "displayAs" : "link",
          "highlightLinks" : true,
        }
      ]
    }
  )
}

Separating visualization definition from IAC configuration

Since options field contains the full JSON encoded string definition of how to render a visualization for the backend API - sql/api/visualizations, they can get quite verbose.

If you have lots of visualizations to declare, it might be cleaner to separate the options field and store them as separate .json files to be referenced.

Example

• directory tree

  .
  ├── q1vx.tf
  └── visualizations
      ├── q1v1.json
      └── q1v2.json

• resource definitions

  ##q1vx.tf
  
  resource "databricks_sql_visualization" "q1v1" {
    query_id    = databricks_sql_query.q1.id
    type        = "table"
    name        = "My Table"
    description = "Some Description"
    options     = file("${path.module}/visualizations/q1v1.json")
  }
  
  resource "databricks_sql_visualization" "q1v2" {
    query_id    = databricks_sql_query.q1.id
    type        = "chart"
    name        = "My Chart"
    description = "Some Description"
    options     = file("${path.module}/visualizations/q1v2.json")
  }

Known Issues

As of 2022-09, databricks sql visualization backend API does not validate the content of what is passed via options, couple that with options being outputted as string in the module, it can lead to configurations which succeed terraform plan but do fail at terraform apply.

In some instances, incorrect definitions within options can lead to stuck terraform states. In preparation for this operational scenario; you should be familiar with, and have sufficient access for, manual inspection and modification of your deployed terraform state.

Import

You can import a databricks_sql_visualization resource with ID like the following:

terraform import databricks_sql_visualization.this <query-id>/<visualization-id>

Related Resources

The following resources are often used in the same context:

• End to end workspace management guide.
• databricks_sql_dashboard to manage Databricks SQL Dashboards.
• databricks_sql_endpoint to manage Databricks SQL Endpoints.
• databricks_sql_global_config to configure the security policy, databricks_instance_profile, and data access properties for all databricks_sql_endpoint of workspace.
• databricks_sql_permissions to manage data object access control lists in Databricks workspaces for things like tables, views, databases, and more.