Unique names
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:
Resource | Scope |
---|---|
Account | Global |
Environment | Account |
Application | Environment |
Data Source | Environment |
Data Pool | Environment |
Metric | Environment |
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) {
id
uniqueName
description
}
}
// Variables
{
uniqueName: "snowflake-production"
}
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:
Resource | Default value |
---|---|
Account | The owner's email followed by the word "Account". For example, "alice@example.com's Account". |
Environment | Production, staging, and development environments are autogenerated by the system with "production", "staging", and "development" unique names. |
Application | The Application's ID. |
Data Source | The Data Source's ID. |
Data Pool | The Data Pool's ID. |
Metric | The Metric's ID. |
Example: Create a Data Pool with unique name "order-items".
// Query
{
createDataPool (input: $createDataPoolInput){
id
uniqueName
description
}
}
// Variables
{
createDataPoolInput: {
dataSource: "snowflake-production",
table: "order_items",
uniqueName: "order-items",
description: "String",
dataRetentionInDays: 90
}
}
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: $modifyDataSourceInput) {
id
uniqueName
description
}
}
// Variables
{
uniqueName: "Production data warehouse"
}
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"