This document helps you to do the following:

• Understand the concept of workspaces in Dataform and their capabilities.
• Create a Dataform development workspace.
• Initialize an empty Dataform development workspace.
• Delete a Dataform development workspace.

Overview of development workspaces

In Dataform, you interact with your workflow code in adevelopment workspace, which is your own editable copy of a repository. In aworkspace, you create, edit, or delete the contents of the repository withoutaffecting others who work on the same repository, and then commit and push yourchanges to the repository.

You can develop your workflow withDataform core orJavaScript.Dataform compiles your code into SQL queries in real time.

In a development workspace, you can perform the following tasks:

• Configure Dataform settings.
• Create tables of all supported types.
• Document tables.
• Partition tables.
• AddBigQuery labels andpolicy tags to tables.
• Override table settings.
• Configure additional actions.
• Declare data sources for your workflow.
• Addcustom SQL operations andtags to your workflow.
• Trigger executionof your workflow or its selected actions.
• Monitor execution logs.

Components of a development workspace

A Dataform development workspace consists of the tabs described inthe following sections.

Code tab

You can use the development environment in theCode tab to explore files,develop queries, version control your changes, and trigger execution toBigQuery. The tab contains the following components that let youdevelop workflows:

• Files pane: displays the file structure of your workspace and autosavesyour edits to the file structure. Selected files open in the tabs of thedevelopment pane. In theType to search field, you can search for filesor directories in your workspace by their path.
• Version control pane: displays the version control status of yourworkspace and the version control options.
• Development pane: displays open files in tabs. Autosaves your changes toedited files.
• Run button: runs apreview of the compiled SQL query.
• Format button: formats your Dataform core or JavaScript code.
• Compilation status: displays the compilation status of the code in yourworkspace.
• Metadata pane: displays the metadata of the edited file.
• Compiled queries pane: compiles the queries in the edited file to SQL. Ifthe query compilation fails, the pane displays the compilation errors. If thequery compilation is successful, the pane displays the compiled queries andvalidates them through dry runs against BigQuery. If the queryvalidation fails, the pane displays the validation errors. If the queryvalidation is successful, the pane displays how many bytes the execution ofthe queries to BigQuery would use.
• Start execution menu: displays the options for triggering the executionof the entire workflow in your workspace or its selected elements.

Compiled graph tab

In theCompiled graph tab, you can see the compiled workflow defined inyour workspace as an interactive directed acyclic graph (DAG). The graph showsall the actions in your workflow and the relationships between them. Ifthere are compilation errors in your workflow, the tab displays an errormessage instead of the graph.

You can zoom in and out and use drag-and-drop navigation in the graph.

You can filter the graph by the following properties:

• Name
• Tag
• Type
  • Assertion
  • Declaration
  • Incremental table
  • Materialized view
  • Operations
  • Table
  • Unknown
  • View

You can select multiple filters at once. Dataform applies themwith theOR condition.

You can click an action in the graph to view its details in the following panes:

• Metadata pane: displays the full name, type, dependencies, and dependentsof the selected action.
• Query pane: displays the compiled SQL query of the selected action.

Executions tab

This tab displays the logs of all the executions triggered in the workspace. Youcan also view actions and their details for a selected execution. For moreinformation, seeMonitor execution logs.

Version control in a workspace

In a workspace, you interact with the repository through Git-based versioncontrol. Edits you make to files in your workspace start off as uncommittedlocal changes that you can commit and then push to your repository so that theybecome available to all repository users.

If your repository is connected to a remote Git provider, you push changesfrom your workspace to your main development branch. You select the main branchwhen you connect your repository to the remote Git provider. In a non-connectedDataform repository, you push changes to the default branch.

You can also pull any changes from the Dataform repository or theremote repository and merge them with local changes in your developmentworkspace. For more information about version control inDataform, seeVersion control your code.

Before you begin

If you haven't done so already,create a Dataform repository.

Required roles

To get the permissions that you need to create, initialize, and delete a development workspace, ask your administrator to grant you theDataform Editor (roles/dataform.editor) IAM role on workspaces. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Create a Dataform development workspace

When you create a development workspace in a new repository for the first time,Dataform prompts you to initialize the development workspace with aset of configuration files that are required for Dataform to work.

An initialized development workspace contains the following directoriesand files:

• definitions/: a directory for asset definitions, in Dataform coreor JavaScript.

• includes/: an empty directory for scripts and variables that you can reuseacross the repository.

• workflow_settings.yaml: the default Dataform configuration filecontaining the Google Cloud project ID and BigQuery schema to publishassets in. You canoverride the default settingsto customize them to your needs, but customization isn't a requirement tobegin using Dataform.

• package.json: the default Dataform dependencies configurationfile with the latest version of@dataform/core. You can use this file toimport packages.

• definitions/sample.sqlx: a sample SQLX file to help you get started.

To create a new Dataform development workspace, follow thesesteps:

1. In the Google Cloud console, go to theDataform page.

   Go to Dataform

2. Select the repository where you want to create the new development workspace.

3. On your repository page, clickCreate development workspace.

4. In theCreate development workspace window, do the following:

   1. In theWorkspace ID field, enter a unique ID for the developmentworkspace.

      IDs can only include numbers, letters, hyphens, and underscores.

   2. ClickCreate.

Note: If you enhance security by setting theenable_private_workspace field(Preview)totrue in theprojects.locations.updateConfig Dataform API method,only the workspace creator can read and write code in thatDataform workspace. This restriction also applies to viewinggenerated artifacts, such as compiled SQL, compilation errors, and run logs,for the workspace's compilations or workflow invocations. For moreinformation, seeEnable private workspaces.

Initialize the workspace in a Dataform repository

To initialize a Dataform development workspace, follow thesesteps:

1. In the Google Cloud console, go to theDataform page.

   Go to Dataform

2. Select the repository where you want to initialize the empty workspace.

3. In theDevelopment workspaces tab, click the name of the emptyworkspace you want to initialize.

4. On the development workspace page, clickInitialize workspace.

Delete a Dataform workspace

There are no costs associated with creating Dataform developmentworkspaces. However, if you want to delete a development workspace, followthese steps:

1. In the Google Cloud console, go to theDataform page.

   Go to Dataform

2. Select the repository that contains the workspace that you want to delete.

3. To avoid deleting uncommitted changes,commit and push changes to your Git repository.

4. In theDevelopment workspaces tab, select the development workspacethat you want to delete, and then clickDelete selected workspaces.

   You can delete multiple workspaces at once.

5. To confirm, clickDelete.

What's next

• To learn how to version control your Dataform code, seeVersion control your code.
• To learn how to create a table, seeCreate a table.
• To learn how to run a preview to test a SQL query, seePreview SQL queries.