Quickbase Language (QBL) uses two distinct types of identifiers to manage solution objects: logical IDs and real IDs. This article explains how these IDs interact, including when they don't match, to help you successfully manage solutions with the Solution APIs.
In this article
Logical IDs
Logical IDs are what Quickbase uses to update the correct objects, and understand what objects across solutions are meant to be the same. These IDs are:
- Stable across solutions: The same logical object maintains its logical ID when moved between solutions
-
Human-readable: IDs are generated from object names and labels with prefixes like
$Field_,$Table_,$App_ - Matching-based: QBL always uses logical IDs to determine which objects correspond to each other
Learn more about logical IDs.
Real IDs
Real IDs are Quickbase's internal identifiers assigned to actual objects in the product. These IDs are:
- Unique and incremental: Each object gets a new real ID when created
-
With various formats: Depending on the type of object, Real IDs might have different formats, like:
- App/Table DBID—
bn5kksx3g - Table alias—
_DBID_SHIPMENTS - Dashboard ID—
61b98c5a-304c-4f03-88dc-51f77d8232ec - Field ID—
5
Note: App and table DBIDs, and dashboard IDs are unique across solutions, so it’s impossible for them to match.
- App/Table DBID—
- Immutable: Real IDs can't be changed once assigned to an object
How logical and real IDs interact
QBL matching is exclusively based on logical IDs, not real IDs. This means that two objects with the same logical ID, but different real IDs, are considered the same object by the Solution APIs.
Referencing an object outside of the solution is always done with its real ID (if allowed). For example, this means that two solutions can refer to the same table that is outside of both solutions.
The following scenarios explain how the presence of logical and real IDs in QBL affect what's created and updated by the Solution APIs.
Scenario 1: Objects have matching logical IDs, but different real IDs
Applies to the Update API only
QBL behavior: Objects are treated as the same entity because they have the same logical ID.
| Object type | Update behavior | Real ID result |
| App (DBID) | Schema updated, data preserved | Not changed |
| App (Manager) | Schema updated, data preserved | Not changed |
| Table (DBID) | Structure updated, records maintained | Not changed |
| Table (Alias) | Structure updated, records maintained | Not changed |
| Field (ID) | Properties updated, field data preserved | Not changed |
| Report (ID) | Definition updated | Not changed |
| Form (ID) | Layout and rules updated | Changed |
| Dashboard (ID) | Layout updated | Not changed |
| Page (ID) | Layout/code updated | Changed |
| Pipeline (ID) | Structure updated | Not changed |
| Pipeline (Owner) | Structure updated | Not changed |
Scenario 2: Objects have logical IDs in the QBL, but not in the solution
Applies to the Create and Update APIs
QBL behavior: Objects are created because they appear as net new to the solution.
| Object Type | Creation behavior | Real ID result |
| App (DBID) | New app created | New ID assigned |
| App (Manager) | New app created | User making the request becomes manager |
| Table (DBID) | New table created | New ID assigned |
| Table (Alias) | New table created | Same ID assigned if available* |
| Field (ID) | New field created | Same ID assigned if available* |
| Report (ID) | New report created | New ID assigned |
| Form (ID) | New form created | Same ID assigned** |
| Dashboard (ID) | New dashboard created | New ID assigned |
| Page (ID) | New page created | Same ID assigned** |
| Pipeline (ID) | New pipeline created | New ID assigned |
| Pipeline (Owner) | New pipeline created | User making the request becomes owner |
*If an object already exists with the same real ID, it won't be changed, so the newly created object will be assigned a new available real ID.
**All real IDs of objects of the same type are updated to match the provided QBL, so newly created objects can use the correct real IDs.
Scenario 3: Objects do not have logical IDs in the QBL, but exist in the target solution
Applies to the Update API only
QBL behavior: Objects may be deleted because they are not present in the QBL definition. Any data that the object carried is permanently deleted.
Before updating a solution, we recommend you export the solution first and check the differences between the provided and exported QBL definitions to analyze what objects will be created, updated, or deleted.
| Object Type | Deletion behavior | Real ID result |
| App (DBID) | API Error | Apps cannot be deleted with the Solution APIs |
| App (Manager) | ||
| Table (DBID) | Table deleted. All data is lost | Cannot be reused by another table |
| Table (Alias) | Can be reused by another table | |
| Field (ID) | Field deleted. All data is lost | Can be reused by another field |
| Report (ID) | Report deleted | Cannot be reused by another report |
| Form (ID) | Form deleted | Can be reused by another form |
| Dashboard (ID) | Dashboard deleted | Cannot be reused by another dashboard |
| Page (ID) | Page deleted | Can be reused by another page |
| Pipeline (ID) | API Error | Pipelines cannot be deleted with the Solution APIs |
| Pipeline (Owner) |
Converting real and logical IDs
In some places (like formulas), objects are referenced by their real IDs by being manually typed in the UI.
Quickbase provides partial support to convert these real IDs to logical IDs and transfer these references across solutions to ensure that the functionality remains intact.
| Area | Conversion support |
| Formula fields |
Partial support:
|
| Code pages |
Partial support:
|
Users, groups, and domain groups
Similarly to records, QBL is not designed to manage the list of users in apps. However, specific users can be referenced in various places in the app (for example, in List-user fields).
In these cases, QBL represents these users with their email address or username.
Solution API warnings
After you successfully create or update a solution, the API may return a list of warnings as part of its response. The main purpose of these warnings is to indicate that although the API operation was successful and the solution passed validation checks, there could be a difference between the real IDs in the provided QBL and the solution.
This is especially important in cases where real IDs are used in places like formulas, pages, and custom role permissions.
Although Quickbase attempts to keep the real IDs of some resources the same, there are cases where this could cause data loss in the solution. In those cases, Quickbase generates new IDs instead, and won’t allow the original IDs to be set the way they appear in the QBL.