Logical IDs

This article explains what a logical ID is, how it's generated, and the correct syntax.

Logical ID definition

Quickbase assigns logical IDs to identify objects in QBL.

Logical IDs help make sure Quickbase updates the correct objects. They also help Quickbase understand what objects across apps are meant to be the same.

For example:

• App A exists in your Quickbase account.

• You export App A to QBL. Then you make a copy: App B.

  • App A and App B have different app IDs, but they have the same logical ID.

• You can make changes on App A, then transfer those changes safely to App B with the solution APIs. The update will produce an exact match because the logical IDs are the same.

Representation in QBL

You can easily find the logical ID that an app, table, or field is mapped to in the QBL by looking for the $ symbol:

In this example, the logical ID for this field is located on row 95, $Field_Project_Name, and the field ID for that field is located on row 97, ID: 16.

How logical IDs are generated

To generate logical IDs for objects in a solution, use the Solution API to export, create, or update the solution. Quickbase generates and assigns logical IDs.

Apps that have never been exported, created, or updated using the Solution API do not have logical IDs.

Updating logical IDs

When Quickbase generates logical IDs, it saves them in the database. You cannot update existing logical IDs, even if you edit the name or label of the object it identifies.

Quickbase automatically updates logical IDs when you change schema. For example, if you delete an object, Quickbase also deletes the logical ID. When you create a new object, Quickbase generates a new logical ID.

Logical ID syntax

Logical IDs consist of:

• Prefix: Object type

  • Field, Role, etc.

• Object name or label

  • If an object does not have a name or label, or the name would somehow invalidate the logical ID, it will be excluded

  • If the name or label is excluded, Quickbase includes an additional index

Logical IDs are:

• Unique within the QBL definition. You can't have 2 fields with the same logical ID.

• No longer than 30 characters after the prefix.

• Made up of characters that are not YAML control characters. If YAML control characters are in the name or label of the object, the API call will fail.

Example logical IDs

Logical IDs in the Solution API

The Solution API allows you to export, create, and update solutions. Here's how logical IDs play a part in each of these requests:

Export

Quickbase creates logical IDs and maps them to each supported object in the solution. See export API documentation.

You can find all logical IDs for supported objects in the QBL YAML file you receive as output.

Create

You use the API to create a new solution that includes apps defined using QBL in a YAML file. See create API documentation. 

Quickbase saves the solution with a logical ID map that is identical to the map in the original YAML file.

Update

Quickbase updates schema objects with matching logical IDs to the QBL definition. See update API documentation. 

For example: