Create and manage workspaces

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

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, seeRequired roles.

Create a workspace

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

Create a workspace in a BigQuery repository

To create a new workspace in a BigQuery repository, followthese steps:

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

   If you don't see the left pane, clicklast_pageExpand left pane to open the pane.

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. In the editor, clickAdd Workspace.

6. In theCreate development workspace pane, in theWorkspace ID field,enter a unique ID for the workspace.

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

7. ClickCreate.

Create a workspace in a third-party repository

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

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. In the editor, clickAdd Workspace. This opens theCreate development workspace pane.

6. Choose either theExisting remote branch orNew branch radio button,depending on whether you want to use an existing or new branch for theworkspace.

7. Specify the branch to use:

   1. If you chose theExisting remote branch radio button, choosean existing branch in theRemote branch field.

   2. If you chose theNew branch radio button, type a branch name in theWorkspace ID field. The branch name created in the third-partyrepository is the same as the BigQuery workspace ID.

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

8. ClickCreate.

Create a directory in a workspace

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

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

6. ClickaddOpen creation menu.

7. ClickCreate in repository> Directory.

8. In theAdd a directory path field, type a directory path.

9. ClickCreate 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 theBigQuery page.

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

6. ClickaddOpen creation menu.

7. ClickCreate in repository and then click the type of file that youwant to create.

8. In theName field, type a filename.

9. Optional: In theParent directory field, type the directory pathin which you want to create the file.

10. ClickSave.

Upload a file

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

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

6. ClickaddOpen creation menu.

7. ClickUpload to repository and then click the type of file that youwant to upload.

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

   • In theFile upload field, clickBrowse, select a file, and thenclickOpen.
   • In theURL field, type the URL for the file.

9. Optional: in theParent directory field, type the directory pathin which you want to create the file.

10. ClickUpload.

Delete a file

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

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

6. Select the file that you want to delete, clickmore_vertView actions, and then clickDelete.

7. ClickDelete to confirm.

Use version control with a file

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

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

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

BigQuery displays the following version control options:

CommitX change(s)

Commit theX number of local changes in your workspaceor selected changed files. BigQuery displays the uncommitted changes.

Push to default branch

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

Push toyour-branch-name

Push your committed changes toyour-branch-name.This option is available in a repositoryconnected to a third-party Git repositoryif you have no uncommitted changes in your workspace. The remote branch namein the third-party repository is the same as the BigQueryworkspace 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 changesin your workspace.

Pull fromyour-branch-name

Update your workspace with recent changes fromyour-branch-name.This option is available in a repositoryconnected to a third-party Git repositoryif you have no uncommitted changes in your workspace. The remote branch namein the third-party repository is the same as the BigQueryworkspace 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 thePull option.

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

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

6. In the workspace pane, do the following:

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

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

      1. ClickPull from default branch to pull from the default branch ofthe third-party repository.
      2. ClickPull fromyour-branch-name to pull from the branch ofthe third-party repository that corresponds to the current workspace.

Commit changes

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

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

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

6. In the workspace pane, clickCommitX changes.

7. In theCommit changes pane, do the following:

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

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

   2. In theAdd a commit message field, type a description for yourcommit.

   3. ClickCommit All changes, orCommitX changes.

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

Push changes

BigQuery displays thePush 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 theBigQuery page.

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

6. In the workspace pane, do the following:

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

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

      1. ClickPush to default branch to push to the default branch ofthe third-party repository.
      2. ClickPush toyour-branch-name to push to the branch ofthe 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 theBigQuery page.

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

6. In the workspace pane, click thearrow_drop_downarrow drop-down on the version control button, and then clickRevert to last commit.

Resolve merge conflicts

A merge conflict can happen when a local change in your workspaceis incompatible with a change that has been made to the default default branchof your repository. Merge conflicts usually occur whenmultiple users simultaneously edit the same file.

You usually encounter a merge conflict when you pull from a branch aftera 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 theBigQuery page.

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

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

7. Commit changes.

8. Optional:Push changes.

View commit history

To view commit history, follow these steps:

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate the workspace and then clickOpen.

   This opens the workspace in thefolder_dataGit repository pane.

   

6. In the workspace pane, click thearrow_drop_downarrow drop-down on the version control button, and then clickView commit history.

Delete a workspace

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

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and then clickRepositories to open theRepositories tab in the details pane.

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

5. Locate your workspace, and then clickmore_vertOpen actions> Delete.

6. ClickDelete.

What's next

• Learn how tocreate repositories.