Share via

Custom format SQL statements

  • Article

Important

This feature is in Public Preview.

This article explains how to customize SQL auto-formatting options in the Azure Databricks UI.

Overview

SQL formatting improves the readability and maintainability of your queries. By standardizing indentation, keyword casing, and other stylistic preferences, a well-formatted query is easier to understand, debug, and share with your team.

In Azure Databricks, you can configure formatting options using a .dbsql-formatter-config.json file saved in your workspace home directory. After saving the file, your SQL code is automatically formatted based on your preferences when you run or format code in the editor or a SQL notebook.

How to configure SQL formatting settings

To configure your personal SQL formatting options:

  1. Click Workspace Icon Workspace in the sidebar.
  2. Click Create > File.
  3. Name the file .dbsql-formatter-config.json.
  4. Add your desired settings as key-value pairs in JSON format. See Formatter options
  5. To apply the latest formatting settings, refresh the page.

Example configuration file

The following example shows a valid .dbsql-formatter-config.json configuration.

{
  "printWidth": 80,
  "indentationStyle": "spaces",
  "indentationWidth": 4,
  "keywordCasing": "uppercase",
  "shouldExpandExpressions": true
}

Formatter options

The following table lists the supported configuration options.

Option Config file name Allowed values Default Description
Print width printWidth Any integer >= 0 100 Sets the target line width for formatted code.
Indentation style indentationStyle 'spaces', 'tabs' 'spaces' Specifies whether to use spaces or tabs for indentation. If set, indentationWidth is ignored.
Indentation width indentationWidth Integer from 0 to 99 2 Number of spaces used when indentationStyle is set to 'spaces'.
Keyword casing keywordCasing 'uppercase', 'lowercase', 'none' 'none' Controls formatting of SQL keywords. 'none' leaves casing unchanged.
Function name casing functionNameCasing 'uppercase', 'lowercase', 'none' 'none' Controls formatting of SQL function names. 'none' leaves casing unchanged.
Comma placement commaPosition 'beginning', 'end' 'end' Controls where commas are placed in lists.
Line breaks between statements numNewLinesBetweenStatements Integer from 0 to 99 1 Number of new lines inserted between statements.
Line breaks between clauses numNewLinesBetweenClauses Integer from 0 to 99 0 Number of new lines inserted between clauses within a statement.
Expand boolean expressions shouldExpandExpressions true, false true Expands boolean expressions onto separate lines.
Expand CASE statements shouldExpandCaseStatements true, false true Expands each clause in a CASE statement onto its own line.
Expand IN lists shouldExpandInStatements true, false false Expands items in IN lists onto separate lines.
Expand BETWEEN conditions shouldExpandBetweenConditions true, false false Expands BETWEEN conditions onto separate lines.
Break JOIN conditions shouldBreakOnJoinSections true, false true Breaks JOIN conditions onto separate lines.