Throughout the Propel API, you will find a uniqueName property in the main Propel resources. The Propel APIs offer the ability to locate a resource by unique name, giving you the option to use a human-readable, unique, and stable name instead of the default alphanumeric ID. This guide explains their intended use, their uniqueness scope, how to use them in the APIs, their limitations, and best practices.

​
Intended use

Unique names provide a convenient way to find a resource by a unique and stable name. This is useful in the following scenarios:
  • Repeatable deployments: When managing your software development lifecycle across development, staging, and production enviroments, you’ll want your deploys to be repeatable, meaning you shouldn’t need to change your code to deploy into different environments. Unique names allow you to easily find a resource by its name rather than its ID, which differs in every environment.
  • Cross-team collaboration: APIs are contracts between systems — and many times — between teams. Unique names allow teams to practice convention over configuration by establishing unique naming conventions instead of having to handle resource IDs in configuration.
  • Human-readable API requests: Human-readable code makes the codebase easier to understand and maintain. Using unique names helps make the intent of the code explicit. A query to the “salesTotal” metric is more reable and easier to understand than a query to the MET01FN9DJZM6J02X73PZBA207YK4 metric.

​
Uniqueness scope

The unique name scope depends on the resource type. There are three possible scopes:
  • Global: The unique name is unique across all Propel for that given resource type.
  • Account: The unique name is unique across the Account for that given resource type.
  • Environment: The unique name is unique across the Environment for that given resource type.
Below are the unique name scopes for the different resources:
ResourceScope
AccountGlobal
EnvironmentAccount
ApplicationEnvironment
Data SourceEnvironment
Data PoolEnvironment
MetricEnvironment

​
Usage

You can use unique names when creating, modifying, or retreiving resources.

​
Retrieving resources

You can retrieve a resource by its unique name. Example: Retrieve an Data Source with unique name “snowflake-production”.
Query
{
  dataSourceByName(uniqueName: {
    uniqueName: "snowflake-production"
  }) {
    id
    uniqueName
    description
  }
}

​
Creating resources

When creating resources, unique names are optional. If no unique name is provided, the API will generate a default name according to the table below:
ResourceDefault value
AccountThe owner’s email followed by the word “Account”. For example, “alice@example.com’s Account”.
EnvironmentProduction, staging, and development environments are autogenerated by the system with “production”, “staging”, and “development” unique names.
ApplicationThe Application’s ID.
Data SourceThe Data Source’s ID.
Data PoolThe Data Pool’s ID.
MetricThe Metric’s ID.
Example: Create a Data Pool with unique name “order-items”.
Mutation
{
  createDataPool (input: {
    dataSource: "snowflake-production",
    table: "order_items",
    uniqueName: "order-items"
  }){
    id
    uniqueName
    description
  }
}

​
Modifying resources

You can modify a resource by its unique name.
Be careful when modifying unique names. If you have application code that expects to be able to fetch a resource by name, you’ll need to roll out the name change in coordination with the code that consumes the API.
Example: Modify a Data Source with unique name “snowflake-production”.
Mutation
{
  modifyDataSourceByName (input: {
    uniqueName: "Production data warehouse"
  }) {
    id
    uniqueName
    description
  }
}

​
Limitations

The unique name property has the following limitations:
  • Minimum length: 1 character
  • Maximum length: 192 bytes (48‒192 characters, depending on characters used)
  • Allowed characters: Any Unicode character
  • The API will automatically trim any leading or trailing whitespace.

​
Best practices

  • Convention over configuration: Set a unique name convention to make them predictable across your application. You can choose any naming convention, like kebab-case, snake_case, or CamelCase, or define your own.
  • Choose specific versus general names: Think of unique names as a namespace. You’ll want to use this namespace wisely and avoid taking over general terms unnecessarily. When possible err on the side of being specific over general.
    • ✅   “sales-total”
    • ❌   “sales”