Screens: Data dictionary

Domains

A domain is a named type rule (type, length, scale, nullable, default, auto increment) shared by values of the same kind. This page covers the screen where you create and edit the domains in a domain pack, and the Document tabDomains tab where you edit domains for a single connection only. How a domain decides a column's type is explained in Data dictionary, and how to create or download a domain pack in Data dictionary manager.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

Select a domain pack in the list on the left of the App menuData Dictionary Management screen and this screen opens on the right. Opening a domain pack from the data dictionary list on the dashboard opens the same pack in the

ScreenDomain management screen.

What's on the screen

No.NameDescription
1HeaderThe visibility icon, the pack name, the language and the latest published version. With unsaved edits, the Unsaved changes badge appears.
2Pack buttonsThe Delete Pack, Export, Discard Changes, Save and Publish buttons. Publishing and backup are covered in Publishing, versions and backup.
3Pack detailsThe Name, Author and Description fields can be edited. The Language field was set when the pack was created and cannot be changed.
4List toolbarThe Add button for a new domain, the domain count, a hint about the add-row shortcut, the number of entries that differ from the published version, the Excel buttons and the search box.
5Domain listOne row per domain. The columns are those in "Domain fields" below. Click a cell to edit it in place. Click a name to open the details window.
6Row buttonsA button that opens the details window, a button that reverts this row's changes (only on changed rows) and a delete button.
  • A domain pack stored on this device (created without signing in, or cloned in a local project) has no Publish button, no Make Public button, and no Members or Versions tab, because it has no publishing step.

Domain fields

FieldMeaning
NameThe name shown when you pick a domain for a column. Names must be unique within a pack (case-insensitive).
TypeA common type. See "Common types and per-DBMS types" below.
Length, ScaleArguments the type takes. The fields lock for types that do not take them. A value above the maximum is changed to that type's maximum with a notice. Types that require a length (such as VARCHAR) warn you when it is empty.
NullableWhether the column accepts NULL.
DefaultThe column default. See "Default values" below.
Auto IncrementCan be turned on only for integer types. Changing to another type treats it as off.
DescriptionA note. It is not copied to columns.

Adding a domain

  1. Click the Add button (4) on the list toolbar. The Add Domain window opens.
  2. Fill in the Name and Type fields, and enter Length and Scale values that suit the type.
  3. Set the Nullable, Auto Increment, Default and Description fields if needed, and click the Add button in the window.
  4. The new row appears in the list. Click the Save button among the pack buttons to save it.
  • Press Ctrl+Enter (Cmd+Enter on macOS) while in a cell to add an empty row right below it without a window. Use it to enter several rows in a row.
  • If a domain with the same name already exists, the Add button in the window stays disabled.

Editing and deleting domains

  1. Click a cell to edit it in place, or click a name (or the details button among the row buttons) to edit it in the Domain Details window.
  2. A changed row is colored and a revert button appears at its end. It discards that row's changes and goes back to the published values in an account asset, or to the saved values in a pack on this device. In a pack on this device the color goes away once you save.
  3. To delete a row, click the delete button among the row buttons and confirm. A deleted row stays struck through until you save, and the revert button brings it back.
  4. Click the Save button. To throw away all edits before saving, click the Discard Changes button. The pack returns to its last saved state.
  • Saving alone does not always change the connections this pack is assigned to. A pack on the server (an official pack or an account asset) is seen by a connection at one published version, and a pack on this device is seen as the copy taken when it was assigned. See "Connections stay at the point you assigned" in Data dictionary.

Common types and per-DBMS types

Domain types are written as common types that do not depend on a DBMS (VARCHAR, DECIMAL, DATETIME, BOOLEAN, JSON and so on). That way one domain pack can be assigned to connections of different DBMSs.

  • When a connection uses a domain, the common type becomes that DBMS's type. For example, VARCHAR becomes VARCHAR2 on an Oracle connection, and the maximum length follows that DBMS.
  • This screen edits only the common type. To pick a type of a specific DBMS, edit the domain on a connection of that DBMS (see "Editing domains for one connection" below). The connection's screen lists that database's types, and the value you pick applies only to that DBMS.
  • On a connection's screen, hover over a type to see its common type, as in Common definition: VARCHAR.

Default values

The default field has three states. In the details window you choose one with the buttons.

StateMeaning
LiteralThe value you enter is used as the default as is. Values that do not fit the type (letters for a number type, a value that is not a date, text longer than the length and so on) cannot be saved.
ExpressionA function such as CURRENT_TIMESTAMP. Pick one from the list or type it. Functions that cannot be used with the type are shown locked with the reason. In the list cell it appears in purple italics.
Not SetThe domain has no default. Assigning this domain to a column clears the column's default.
  • If you type a function under a name only one DBMS understands, a suggestion to switch to the standard name (Replace with CURRENT_TIMESTAMP) appears. Click it to replace the value. It is never replaced automatically.

Editing domains for one connection

You can edit the domain pack assigned to a connection for that connection only. The source pack does not change. There are two places to edit, and they show the same edits. A change in one appears in the other.

  • The Document tabDomains tab, which opens when you click the Data Dictionary › Domains node under a connection in the explorer. It is covered on this page.
  • The Project railData Dictionary panel on the right rail. It is covered in Assigning to a connection.
No.NameDescription
1ToolbarThe search box, the domain count, the 2 unsaved indicator, the Add domain button, the Delete button, the Discard all button and the Save (2) button.
2Domain listThe same columns as the manager, but type, length and scale show this connection database's values. Unsaved rows are colored.
  1. In the explorer, expand the Data Dictionary node under the connection and click the Domains node. The tab is titled with the assigned pack's name.
  2. Edit cells, add a domain with the Add domain button, or select a row and click the Delete button.
  3. Click the Save (1) button. Instead of saving right away, the Domain change impact window opens first.
  4. The window finds the columns on this connection that use those domains and shows which columns change and how. Review it and click the Save and apply button.
  5. The domain edits are saved, the new values are written to the selected columns, and those tables are saved.
  • Columns whose type, length or scale differ are updated. Columns that differ only in nullable, default or auto increment are updated only when the Apply 'nullable · default · auto increment' changes checkbox is on, because those values may legitimately differ per column. If you changed those values in the domain, the window opens with the checkbox on, so turn it off if some columns should keep their own values.
  • If a table already has an auto increment column, everything except auto increment (type, length, nullable, default) is applied to that column, with a notice. This is the same rule as when you pick a domain for a column. Tables someone else is editing are skipped too.
  • Tables whose database metadata could not be read appear separately under the 1 tables could not be read group. The Scan again button reads them again.
  • Columns pointing at a domain that cannot be found appear under the 1 broken domain bindings group. Their assignment is never removed automatically.
  • If saving fails partway, it stops and tells you how many tables remain. Applying again resumes from the remaining tables.
  • If a domain whose type requires a length has no length, the window does not open and the domain names are listed instead.

What changes when a column uses a domain

The column lists of the ERD and the table tab have a Domain column. It can be used when a domain pack is assigned to the connection.

ActionWhat happens to the column
Pick a domainThe domain's type (in that DBMS's type), length, scale, nullable, default and auto increment are copied to the column. A domain whose default is Not Set clears the column's default.
Edit a value the domain decides directly on the columnThe column's domain assignment is removed. The edited value stays.
Change the domain to the None optionOnly the assignment is removed. The column's values stay as they are.
Edit and save the domain on the connectionThe Domain change impact window above writes new values only to the columns you select.
Edit the source pack in the managerColumns do not change, because the version or copy the connection sees stays the same.
  • Because values are copied to the column, the ERD and DDL keep working even when the pack cannot be opened.
  • A changed column value is a change to the table design. It reaches the live database only after you apply the changes (Apply changes to the database).
  • Entering a column's logical name can also pick a domain through the dictionary. See "One logical name sets both name and type" in Data dictionary.

Things to keep in mind

  • Unsaved domains cannot be picked in a column's Domain column. Domains created on a connection's screen also appear only after saving.
  • Saving on a connection's screen also saves the tables of the columns that use those domains. Check the list in the impact window before saving. Applying a change that shortens a length to the database can truncate data.
  • In an account project, if your role has the Domain restriction permission, you cannot edit the connection's domains. You can still pick domains for columns. The same applies when you lack permission to edit the connection.
  • After a domain is deleted, columns that used it keep a broken assignment. The column values stay as they are.
  • The Language field cannot be changed after creation.