Tools → Schema Designer → Modes and Versions

About the Schema Designer Versions

Incorta Cloud tracks the version history of physical schemas in your tenant. With the proper access rights and permissions, you can restore or export prior physical schema versions. Starting from the 2021.4.1 release, Incorta Cloud supports saving changes and updates you make to the physical schema objects and joins to a draft version instead of directly publishing these changes in a saved version. A user can have multiple saved versions of the same physical schema, but only one draft version of it. The Schema Designer functions differently when editing a saved version and a draft version.

For information about the access rights and permissions required for each action, refer to Tools → Schema Designer → Schema Designer permissions and access rights.

Schema Designer Modes

The Schema Designer supports two different modes:

Saved Version mode

This is the default mode when you access the Schema Designer. A saved version is created for a physical schema after a schema update job. You trigger a schema update job when you select Save Changes to promote a draft version or when you import a physical schema that overwrites an existing one.

Creating a new physical schema or importing one does not lead to creating a draft version of the physical schema. This directly creates a saved version.

Important

The Cluster Management Console (CMC) tenant or default tenant configurations have settings to define the maximum number of versions to maintain and how often a separate saved version is created when you select to promote a draft to a saved version (select Save Changes in the Schema Designer Action bar). These settings are Tenant Configurations / Default Tenant Configurations → Incorta Labs → Maximum number of versions per entity and Backup frequency.

If you set the Backup frequency option to a specific period, you will append new changes to the current unnamed version each time you select Save Changes during this period. If you set it to Keep all versions, you will create a separate saved version each time you select Save Changes. This applies only to unnamed versions. Once you name a saved version, you cannot save changes to it. In this case, a new version is created.

With the proper access rights and permissions, you can do the following in this mode:

  • Start a new draft version or edit the existing draft to add, edit, and delete the physical schema objects and joins
  • Access the Load Job Viewer and Model Update Viewer to view data load jobs and schema update jobs respectively
  • Load data
  • Explore the physical schema data
  • Access the physical schema Settings menu (gear icon) and use available options including managing the physical schema draft and saved versions

If you have a draft version of the physical schema, when you access the Schema Designer, a banner message appears denoting that you can either overwrite the draft or open it to accumulate new updates to it.

Important

If another user is opening a physical schema in the draft mode and is previewing a valid draft of it (not an obsolete draft), you cannot make any updates to this physical schema, delete it, or overwrite it with another imported one. However, you can load its data, load one of its objects’ data, explore data, view the physical schema diagram, view object details, and view join details.

You may need to refresh the Schema Designer page to check if the physical schema is released or not.

Draft mode

You can access the draft mode for a physical schema when you do one of the following:

  • After updating the physical schema, such as creating a new object or deleting one
  • After saving updates in the Table Editor (after you select Done)
  • After saving updates in the Join Editor (after you select Done)
  • When you preview or edit a draft (Settings (gear icon) → Version HistoryDraft Versions tab → More Options (⋮ vertical ellipsis) → Preview)
  • When you select to edit your existing draft (select the link in the message banner)

With the first update you make, Incorta creates a draft version of the physical schema and accumulates to this draft any further updates you make. For example, when you create a formula column in the Table Editor and then select Done in the Action bar, this creates a new draft or updates an existing draft, whether this existing draft belongs to you or another user and you are editing it.

In addition, if the session times out while you have physical schema updates that you did not save, the system will keep these updates in the draft version for you.

Note

When you edit a physical schema in the draft mode, you block other users from updating the physical schema until any of the following happens:

  • You promote the draft changes to a saved version.
  • You keep the changes in the draft version.
  • You sign out from Incorta.
  • You close the browser (after 5 minutes from closing the browser).
  • The session ends.
  • The Analytics Service is down.

When you preview or edit a draft version, and then you try to exit the Schema Designer by selecting any tab on the navigation bar, the load job status, or the model update status, you have the following options:

  • Keep the changes in the draft version
  • Save the changes to a published version (that is, promote the draft changes to a saved version)
  • Discard the changes and delete the draft version
Important

When you promote a draft to a saved version, you invoke a schema update job that you can preview its status in the Model Update Viewer. During a schema update job, you and other users cannot do any of the following:

  • Run another update job, so when you select to promote a draft version to a saved one (select Save Changes), you get a message that another update job is running
  • Import a physical schema that overwrites this physical schema
  • Run a load job

Each user has only one draft version per physical schema. If you have a draft version for a given physical schema and you access the Schema Designer for this physical schema in the saved version mode, the Schema Designer shows a message to confirm that you already have a draft and if you want to make changes to this physical schema, you can either overwrite the existing draft with the new changes you will make or open the draft version and accumulate your changes to this draft.

In the draft mode, you cannot load or explore data. In addition, the Rows and Data Size properties for the physical schema and its objects are dimmed as they may show incorrect information.

When you create a saved version of a physical schema, you obsolete all existing drafts, including your draft and other users’ drafts. When you preview an obsolete draft, you cannot edit it or promote it to a saved version; however, you can discard this draft and start a new one from the saved version. When you discard an obsolete draft version, the Schema Designer opens the saved version mode.

As a schema manager user, you can preview a draft of a physical schema that you own or have Edit access rights to. You can also promote a draft to a saved version as long as this draft is not obsolete.

Important

When you create an MV in a draft version, MV validation is run against the draft version, not the saved version of the physical schema.

Schema Designer actions for a draft

Using the Schema Designer, you can perform the following actions for physical schema draft versions:

Create a physical schema draft

By default, when you make changes to the physical schema using the Table Editor or the Join Editor, you create or edit a draft version of the physical schema. In addition, when you add or delete a physical schema object or join relationship in the Schema Designer, you create or edit a draft.

Note

When you load data or edit the physical schema settings, such as the description or the load order, this does not create or edit a physical schema draft.

Here are the steps to create a physical schema draft:

  • In the Navigation bar, select Schema.
  • In the list view of schemas, select a given physical schema.
  • In the Schema Designer, make your changes to the physical schema.

When you try to exit the Schema Designer and when prompted to save your changes, select Keep As Draft.

Search or filter the draft version history

  • In the Schema Designer, in the Action bar, select Settings (gear icon), and then select Version History.
  • In the Version history drawer, select specify the filter criteria as required:
    • For Version Date, select a period to search for drafts created or updated within this period. You can select a predefined period, such as Yesterday and Last 7 days (including today), or select custom, and then specify the period’s start and end dates.
    • For Modified By, the name of the user who last updated the drafts you search for.
    • Enable the Only Show Named Versions toggle to show only named versions.
  • Select the Draft Versions tab to view drafts that match the filter options you specified.

Name a draft version

  • In the Schema Designer, in the Action bar, select Settings (gear icon), and then select Version History.
  • In the Version history drawer, optionally, search for the draft you want.
  • For a given draft, select the draft name (by default, the draft creation or update time is the draft name).
  • Specify a new name for the draft version, and then press ENTER or select any other place in the drawer or the Schema Designer.
Note

A draft name can have alphanumeric or special characters. The length of a draft name cannot exceed 50 characters including spaces.

Preview a draft

You can preview drafts created by other users.

  • In the Schema Designer, in the Action bar, select Settings (gear icon), and then select Version History.
  • In the Version history drawer, optionally, search for the draft you want.
  • For a given draft, select More Options (⋮ vertical ellipsis), and then select Preview.
Note

When you access the Schema Designer of a physical schema for which you have a draft, the message banner shows a message that links to this draft. Select the message to preview and edit the draft.

Promote a valid draft to a saved version

You can promote only a valid, non-obsolete draft after creating or editing it or while previewing it. Promoting a draft removes it from the draft versions list. When you promote a named draft, the saved version will have the name of this draft.

Here are the steps to promote a daft after creating it:

  • Use the Schema Designer, Table Editor, or Join Editor to make your updates.
  • In the Schema Designer, in the Action bar, select Save Changes.

Here are the steps to promote a valid daft while previewing it:

  • In the Schema Designer, in the Action bar, select Settings (gear icon) → Version History.
  • For a given draft, select More Options (⋮ vertical ellipsis) → Preview.
  • In the Action bar, select Save Changes.
Note

You can also preview a draft that you have of a physical schema using the message banner. The Save Changes option is available when the draft is still valid. Otherwise, the message banner shows that the draft is obsolete, and you cannot edit or promote this draft.

Here are the steps to promote a valid daft after editing it:

  • In the Schema Designer, in the Action bar, select Settings (gear icon) → Version History.
  • For a given draft, select More Options (⋮ vertical ellipsis) → Preview.
  • Use the Schema Designer, Table Editor, or Join Editor to make the updates you want to append to the draft.
  • In the Action bar, select Save Changes.

Discard changes in a valid draft

  • After creating or editing a draft or while previewing a valid one, try to exit the Schema Designer by selecting any tab in the navigation bar or selecting the Last Load Status or Model Update Status link.
  • In the dialog, select Discard Changes.

Discard an obsolete or invalid draft

When you preview an obsolete draft, the message banner shows that you cannot edit or save this draft. To discard the changes in this obsolete draft and delete it, in the message banner, select Discard Draft. The draft is deleted from the draft versions list.


Schema Designer actions for a saved version

Using the Schema Designer, you can perform the following actions for physical schema saved versions:

Search or filter the saved version history

  • In the Schema Designer, in the Action bar, select Settings (gear icon), and then select Version History.
  • In the Version history drawer, specify the filter criteria as required:
    • For Version Date, select a period to search for saved versions created or restored within this period. You can select a predefined period, such as Yesterday and Last 7 days (including today), or select custom, and then specify the period’s start and end dates.
    • For Modified By, the name of the user who created the version you search for.
    • Enable the Only Show Named Versions toggle to show only named versions.
  • Select the Saved Versions tab to view saved versions that match the filter options you specified.

Name a saved version

  • In the Schema Designer, in the Action bar, select Settings (gear icon), and then select Version History.
  • In the Version history drawer, optionally, search for the saved version you want.
  • For a given saved version, select the version name (by default, the version creation or restore time is the version name).
  • Specify a new name for the saved version, and then press ENTER or select any other place in the drawer or the Schema Designer.
Note

A version name can have alphanumeric or special characters. The length of a version name cannot exceed 50 characters including spaces.

Export a saved version

  • In the Schema Designer, in the Action bar, select Settings (gear icon), and then select Version History.
  • In the Version history drawer, optionally, search for the saved version you want.
  • For a given saved version, select More Options (⋮ vertical ellipsis) → Export.
  • In the Export Schema(s) dialog, optionally select the Include scheduled jobs/Include load plans check box to include the scheduled jobs related to this physical schema.
  • Select Export. The exported physical schema .zip file is saved to the Downloads folder.
Note
  • Starting with 2023.7.0, the Include scheduled jobs option becomes Include load plans.
  • Exporting a schema with its load plans will include only single-schema load plans that include this schema.

Restore a saved version

When you restore a saved version of a physical schema, a copy of this version becomes the current version. The default name of the copied version is its restore (creation) time. The original saved version remains as is with its name and creation date.

Here are the steps to restore a saved version of a physical schema:

  • In the Schema Designer, in the Action bar, select Settings (gear icon), and then select Version History.
  • In the Version history drawer, optionally, search for the saved version you want.
  • For a given saved version, select More Options (⋮ vertical ellipsis) → Restore.