LogoLogo
  • Welcome to Gretel!
  • Gretel Basics
    • Getting Started
      • Quickstart
      • Blueprints
      • Use Case Examples
      • Environment Setup
        • Console
        • SDK
      • Projects
      • Inputs and Outputs
      • Gretel Connectors
        • Object Storage
          • Amazon S3
          • Google Cloud Storage
          • Azure Blob
        • Database
          • MySQL
          • PostgreSQL
          • MS SQL Server
          • Oracle Database
        • Data Warehouse
          • Snowflake
          • BigQuery
          • Databricks
        • Gretel Project
    • Release Notes
      • Platform Release Notes
        • May 2025
        • April 2025
        • March 2025
        • February 2025
        • January 2025
        • December 2024
        • November 2024
        • October 2024
        • September 2024
        • August 2024
        • July 2024
        • June 2024
      • Console Release Notes
        • January 2025
        • December 2024
        • November 2024
        • October 2024
        • September 2024
        • August 2024
      • Python SDKs
  • Create Synthetic Data
    • Gretel Safe Synthetics
      • Transform
        • Reference
        • Examples
        • Supported Entities
      • Synthetics
        • Gretel Tabular Fine-Tuning
        • Gretel Text Fine-Tuning
        • Gretel Tabular GAN
        • Benchmark Report
        • Privacy Protection
      • Evaluate
        • Synthetic Quality & Privacy Report
        • Tips to Improve Synthetic Data Quality
        • Data Privacy 101
      • SDK
    • Gretel Data Designer
      • Getting Started with Data Designer
      • Define your Data Columns
        • Column Types
        • Add Constraints to Columns
        • Custom Model Configurations
        • Upload Files as Seeds
      • Building your Dataset
        • Seeding your Dataset
        • Generating Data
      • Generate Realistic Personal Details
      • Structured Outputs
      • Code Validation
      • Data Evaluation
      • Magic Assistance
      • Using Jinja Templates
  • Gretel Playground [Legacy]
    • Getting Started
    • Prompts Tips & Best Practices
    • FAQ
    • SDK Examples
    • Tutorials
    • Videos
    • Gretel Playground [Legacy] Inference API
    • Batch Job SDK
  • Reference
    • Gretel's Python Client
    • Gretel’s Open Source Synthetic Engine
    • Gretel’s REST API
    • Homepage
    • Model Suites
Powered by GitBook
On this page
  • Projects Overview
  • SDK Project Management
  • Creating Projects
  • Unique Project Name Helper
  • Temporary Projects
  • Accessing Projects
  • Deleting Projects

Was this helpful?

Export as PDF
  1. Gretel Basics
  2. Getting Started

Projects

Learn to use and manage projects that allow you to store and collaborate on data.

PreviousSDKNextInputs and Outputs

Last updated 27 days ago

Was this helpful?

Projects Overview

Gretel Projects can be thought of as repositories that hold models. Projects are created by single users and can be shared with various permissions:

  • Read: Users may access data artifacts (such as synthetic data and reports)

  • Write: Users may create and run models.

  • Administrator: Users may add other users to a project.

  • Owner: Full control.

The most important thing to note about Projects is that the name attribute of a project is globally unique. If you are familiar with services like Simple Storage Service (S3), then Project naming will feel very similar since S3 bucket names are also globally unique within a specific service provider (such as AWS).

Projects have the following attributes you should be familiar with:

  • name: A globally unique name for the project. When you create a project without specifying a specific name, Gretel will generate one for you. This will be a randomized name based on your username and a unique hash slug. If you specify a name that is already used, Project creation will fail.

  • display_name: This can be any descriptive name for the Project that will control how the Project is listed and displayed in the Gretel Console. It is non-unique.

  • description: This optional field can be provided to provide a user-friendly description of the Project.

When using the SDK and you need to specify a Project parameter or variable, you should ensure you are using the Project name (unique key).

We are introducing new ID values that we call Gretel UIDs, for projects these will be randomized values that are prefixed with proj_. You may start seeing this in lieu of Project names but they are effectively the same. A full example of a Project GUID is: proj_2BGDjIP0B2nx3RmNw8rURRUm0dz.

SDK Project Management

The Gretel Python SDK gives more flexibility and control around Project management. Within the SDK, the should be the primary orientation point for doing most of your work with Gretel.

The SDK differs in that when creating or accessing Projects, you will be given an instance of a Project class that you can interact with. Let's take a look.

Creating Projects

You can create a project with no input attributes:

from gretel_client import create_project

proj = create_project()

proj.name
# 'john-a6cbf'

proj.get_console_url()
# 'https://console.gretel.cloud/john-a6cbf'

Alternatively, you can provide Project attributes to the create_project() method:

from gretel_client import create_project

proj = create_project(name="my-awesome-project", display_name="Projects 101")

proj.name
# 'my-awesome-project'

proj.get_console_url()
# 'https://console-dev.gretel.cloud/my-awesome-project'

Unique Project Name Helper

As mentioned earlier, Project names are globally unique. However, we have created a utility in the SDK that allows users to "share" identical project names such that any user could have their own version of a project called "test" or "foo".

This helper will either create a new project or fetch an existing one, giving you back a Project instance. Additionally, the display name of the project will automatically be set for you based on the name you provide. Let's take a look:

from gretel_client import create_or_get_unique_project

proj = create_or_get_unique_project(name="my-new-awesome-project")

proj.name
# 'my-new-awesome-project-92fbf5bd55d2472'
# NOTE: The slug at the end is automatically handled by the SDK

proj.display_name
# 'my-new-awesome-project'
# NOTE: This will be the display name in the console

In this mode, every user could use the exact my-new-awesome-project string and a unique slug for that user will be appended to the Project name. This may be especially useful if you are re-running Notebooks or routines and do not want to use a combination of create_project() and get_project() to determine if a project already exists or not.

Temporary Projects

In certain occasions, you may want to create a Project only for the purposes of creating a model and extracting the specific outputs (Synthetic Data, Synthetic Quality Report, etc). Once you have extracted the data you need, you can delete the Project, which will then delete all of the models and artifacts related to those models.

For this use case, there is a temporary project context manager you can use. Once the context handler exits, the Project will be deleted:

# NOTE: This import is one package down in the `projects` package

from gretel_client.projects import tmp_project

with tmp_project() as my_tmp_project:
    print(my_tmp_project.name)
    # 'john-3a8ae'

# At this point, our project has been deleted.

Accessing Projects

If you already have a Gretel Project, in order to run model operations, you will need to load an instance of the Project class in the SDK. We'll use our example Project from above: my-awesome-project to show how to do this.

from gretel_client import get_project

proj = get_project(name="my-awesome-project")

proj.name
# 'my-awesome-project'

Deleting Projects

To delete a project from the SDK, you utilize the delete() method on a Project instance:

from gretel_client import create_project

proj = create_project()

proj.delete()

Once you delete a project, the class instance is not usable anymore. If you try and do any meaningful operation with it, you'll receive a GretelProjectError such as:

GretelProjectError: Cannot call method. The project has been marked for deletion.

Projects module and class