Create and use workspaces

This document shows you how to work with workspaces in BigQuery, including the following tasks:

• Creating workspaces
• Deleting workspaces
• Working with files in workspaces
• Performing version control on files in workspaces

Before you begin

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

Required roles

Access to workspaces is determined by roles granted on their parent repository. For more information, see Required roles.

Create a workspace

Workspace creation is handled differently based on whether you are using a BigQuery repository or a third-party repository.

Create a workspace in a BigQuery repository

To create a new workspace in a BigQuery repository, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository in which you want to create a workspace.

4. In the editor, click Add Workspace.

5. In the Create workspace pane, in the Workspace ID field, enter a unique ID for the workspace.

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

6. Click Create.

Create a workspace in a third-party repository

To create a new workspace in a third-party repository, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository in which you want to create a workspace.

4. In the editor, click Add Workspace. This opens the Create workspace pane.

5. Choose either the Existing remote branch or New branch radio button, depending on whether you want to use an existing or new branch for the workspace.

6. Specify the branch to use:

   1. If you chose the Existing remote branch radio button, choose an existing branch in the Remote branch field.

   2. If you chose the New branch radio button, type a branch name in the Workspace ID field. The branch name created in the third-party repository is the same as the BigQuery workspace ID.

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

7. Click Create.

Create a directory in a workspace

To create a directory in a workspace, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and click Open.

   This opens the workspace pane:

   

5. Click the add Add option.

6. Click Create in repository > Directory.

7. In the Add a directory path field, type a directory path.

8. Click Create Directory.

Work with files in a workspace

You can create new files in a workspace, or upload existing files.

You can create or upload the following types of files to a repository:

• SQL queries
• Python notebooks
• Data canvases
• Data preparations
• Files of any other type

Create a file

To create a file in a workspace, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and then click Open.

   This opens the workspace pane:

   

5. Do one of the following:

   • Click the add Add option.
   • Select an existing directory and click the more_vert Actions option.

6. Click Create in repository and then click the type of file that you want to create.

7. In the Name field, type a filename.

8. Optional: In the Parent directory field, type the directory path in which to create the file.

9. Click Save.

Upload a file

To upload a file to a workspace, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and then click Open.

   This opens the workspace pane:

   

5. Do one of the following:

   • Click the add Add option.
   • Select an existing directory and click the more_vert Actions option.

6. Click Upload to repository and then click the type of file that you want to upload.

7. In the upload pane, do one of the following:

   • In the File upload field, click Browse, select a file, and then click Open.
   • In the URL field, type the URL for the file.

8. Optional: in the Parent directory field, type the directory path in which to create the file.

9. Click Upload.

Delete a file

To delete a file from a workspace, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and then click Open.

   This opens the workspace pane:

   

5. Select the file that you want to delete, click the more_vert Actions option, and then click Delete.

6. Click Delete.

Use version control with a file

This section shows you how to use version control in BigQuery to keep track of files in workspaces.

BigQuery uses Git to keep track of each change made to the files inside a repository. In a BigQuery repository, you interact directly with the Git repository. In a connected repository, you interact with the default branch of the remote repository that you configured when you connected the repository.

BigQuery displays version control options based on the status of changes in your workspace. For example, BigQuery displays the commit option only when there are uncommitted local changes in your workspace. When the files in your workspace are an exact copy of your default or default branch, BigQuery displays the Up to date status.

BigQuery displays the following version control options:

Commit X change(s)

Commit the X number of local changes in your workspace or selected changed files. BigQuery displays the uncommitted changes.

Push to default branch

Push your committed changes to your default branch. This option is available in a repository if you have no uncommitted changes in your workspace and there are unpushed commits.

Push to your-branch-name

Push your committed changes to your-branch-name. This option is available in a repository connected to a third-party Git repository if you have no uncommitted changes in your workspace. The remote branch name in the third-party repository is the same as the BigQuery workspace ID.

Pull from default branch

Update your workspaces with recent changes from your default branch. This option is available in a repository if you have no uncommitted changes in your workspace.

Pull from your-branch-name

Update your workspace with recent changes from your-branch-name. This option is available in a repository connected to a third-party Git repository if you have no uncommitted changes in your workspace. The remote branch name in the third-party repository is the same as the BigQuery workspace ID.

Revert to last commit

Restore the files in your workspace to their state from your last commit.

Pull changes

If your workspace is out of sync with your repository, BigQuery displays the Pull option.

To pull changes from your repository to your workspace, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and click Open.

   This opens the workspace pane:

   

5. In the workspace pane, do the following:

   1. If you are in a BigQuery repository, click Pull from default branch.

   2. If you are in a repository connected to a third-party Git repository, do one of the following:

      1. Click Pull from default branch to pull from the default branch of the third-party repository.
      2. Click Pull from your-branch-name to pull from the branch of the third-party repository that corresponds to the current workspace.

Commit changes

After you make a change in a workspace, BigQuery displays the Commit option. You can commit all local changes or selected files. Files that you have added or modified are identified with a blue dot next to them in the workspace pane.

To commit changes from your workspace to your repository, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and click Open.

   This opens the workspace pane:

   

5. In the workspace pane, click Commit X changes.

6. In the Commit changes pane, do the following:

   1. Select the changed files that you want to commit.

      If you don't select any files, BigQuery commits all local changes. You can filter changed files by file state, filename, and path.

   2. In the Add a commit message field, type a description for your commit.

   3. Click Commit All changes, or Commit X changes.

      The button name depends on your selection of files to commit.

Push changes

BigQuery displays the Push option after you commit changes.

To push changes from your workspace to your repository, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and click Open.

   This opens the workspace pane:

   

5. In the workspace pane, do the following:

   1. If you are in a BigQuery repository, click Push to default branch.

   2. If you are in a repository connected to a third-party Git repository, do one of the following:

      1. Click Push to default branch to push to the default branch of the third-party repository.
      2. Click Push to your-branch-name to push to the branch of the third-party repository that corresponds to the current workspace.

Revert uncommitted changes

To revert uncommitted changes, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and click Open.

   This opens the workspace pane:

   

5. In the workspace pane, click click the arrow_drop_down arrow drop down on the version control button, and then click Revert to last commit.

Resolve merge conflicts

A merge conflict can happen when a local change in your workspace is incompatible with a change that has been made to the default default branch of your repository. Merge conflicts usually occur when multiple users simultaneously edit the same file.

You usually encounter a merge conflict when you pull from a branch after a different user has pushed a conflicting change to the same branch. You need to resolve a merge conflict manually by editing the affected file.

The following code sample shows a merge conflict displayed in a SQL file:

    <<<<<<< HEAD
    SELECT 1 as CustomerOrders
    =======
    SELECT 1 as Orders
    >>>>>>> refs/heads/main

To resolve a merge conflict, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and click Open.

   This opens the workspace pane:

   

5. Select the affected file and edit it with your chosen changes.

6. Commit changes.

7. Optional: Push changes.

View commit history

To view commit history, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, expand the Repositories folder.

3. Select the repository that contains the workspace that you want to work with.

4. In the editor, locate the workspace and click Open.

   This opens the workspace pane:

   

5. In the workspace pane, click click the arrow_drop_down arrow drop down on the version control button, and then click View commit history.

Delete a workspace

To delete a workspace and all its contents, follow these steps:

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

   Go to BigQuery

2. In the Explorer pane, click the Repositories folder.

3. In the Git Repositories pane, select the workspace that you want to delete.

4. Click the more_vert Actions option and then click Delete.

5. Click Delete.

What's next

• Learn how to create repositories.