Walkthroughs

Use standard names from a data dictionary

You put your organization's naming rules into a dictionary, assign it to a connection, and make typing only a column's logical name (for example, Order Datetime) in an ERD set both the standard physical name (ord_dtm) and the type. For columns that already exist in the database, you compare them with the dictionary to find mismatches and decide yourself whether to fix them. It takes about 30 minutes.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

Which assets you can assign depends on the project. Follow along either in a local project in the desktop app without signing in, or in an account project while signed in. If you do it in a local project while signed in, the dictionary you create in the manager becomes an account asset and does not appear in the assignment list ('What local projects can assign' in Data dictionary).

Before you start

  • You need a connection to the demo store database and an ERD on the connection (Document an existing database as an ERD).
  • First read how words decide names, domains decide types, and how a combination dictionary reads logical names (Data dictionary).
  • These are the domains and words used in the examples. If your organization has its own standard, follow along with that instead.
DomainType
AmountDECIMAL(15,2)
DatetimeDATETIME
FlagCHAR(1)
NumberVARCHAR(20)
WordAbbreviationDomainRelations
OrderORD
CustomerCUST
DatetimeDTMDatetimeSynonym Date
NumberNONumber
AmountAMTAmount
UseUSE
FlagYNFlag
StartSTRTAntonym End
EndEND

Creating a domain pack

  1. In the app menu, open the App menuData Dictionary item and click the App menuData Dictionary Management item. Result: The data dictionary manager opens.
  2. Click the New button and choose the Domain item in the Type field. Enter Demo Domains in the Name field and click the Save button. Result: A domain pack to hold the type rules is created. Without signing in it is an asset on the device; when signed in it is an asset in your account.
  3. Add the four domains in the table above with the Add button on the Domains tab, then click the pack's Save button. Result: The four domains are saved in the pack.

The domain fields and DBMS-specific types are covered in Domains. If you will use an official pack provided by NeoSQL as is, skip this step and choose the official pack as the dictionary's domain pack in the next step.

Creating a dictionary and adding words

  1. Click the New button and choose the Dictionary item under the kind (1).
  2. Choose the Combination item under the dictionary type (2), enter Demo Dictionary as the name and save. Result: Demo Dictionary is created as a combination dictionary. The dictionary type cannot be changed later.
  3. In the dictionary's Domain Pack field, click the Select domain pack button and choose Demo Domains. Result: The domain pack the dictionary uses is set to Demo Domains.
  4. Add the words in the table above with the Add button on the Words tab. For each word, fill in the Word field, the Abbreviation field and the Domain field; give Datetime the synonym Date, and give Start the antonym End. Result: An antonym is recorded on both words.
  5. Click the dictionary's Save button. Result: One dictionary now holds and saves the rule for reading a logical name as words and joining their abbreviations, and which domain each word uses.

The word fields, and the difference between synonyms, antonyms and related words, are covered in Words.

Assigning it to a connection

  1. In the project's explorer, right-click the shop-db connection and choose the Explorer context menuData Dictionary... menu. Result: The connection dialog opens on the Data Dictionary tab.
  2. Click the Select Dictionary button (5) and choose Demo Dictionary. For an account asset, choose a version as well. Result: The Demo Dictionary card appears in the dialog.
  3. Check that Demo Domains, set by the dictionary, came along into the Domain slot (2).
  4. Click the dialog's Save button. Result: ERDs and table tabs on the connection now read logical names with the dictionary. A connection sees the dictionary as it was when assigned, so later edits to the dictionary do not change the connection by themselves (Assigning to a connection).

Assignment is per connection, not per project. Other connections in the same project can have a different dictionary or none.

Creating new columns from logical names

  1. Open an ERD of shop-db and click the Logical mode button in the info panel. Result: The Logical Name cell appears in the column grid, and because the connection has a domain pack assigned, the Domain cell appears too.
  2. Place a new table with the Add New Table button and type Customer Order into the logical name field in the table header. Result: The table name changes to cust_ord. The dictionary splits the logical name into words and joins their abbreviations with _, following the connection DBMS's case rules.
  3. Add a column with the grid's + button and type Order Datetime into the Logical Name cell (1). Result: The physical name (2) becomes ord_dtm, the domain (3) becomes Datetime, and the type (4) is filled in from the domain.
  4. Add Order Number, Customer Number, Order Amount and Use Flag the same way. Result: If there is one domain candidate from the last word, it is assigned right away; if there are several, it remains as a grey suggestion in the domain cell. Click the check mark in the cell to assign the suggestion.
  5. Try typing a synonym, such as Order Date. Result: The logical name changes to the standard words Order Datetime, and the physical name becomes ord_dtm.
  • The columns of a new table do not exist in the database yet, so their names and types change right away. When you are done, create the real table with Apply changes to the database.
  • If you edit a value the domain decides (type, length, nullability and so on) directly in the column, the column's domain assignment is removed.
  • On a DBMS that allows only one auto-increment column per table, if another column is already auto-increment, the domain's values are applied without its auto-increment.
  • If a column with the same name already exists, the physical name is not changed and the Could not rename to ord_dtm. A column with that name already exists notification appears.

Reading the marks in the logical name cell

What the dictionary read stays as marks in the logical name cell. The marks are not saved; they are recalculated from the dictionary every time, so they follow when you edit the dictionary.

MarkMeaning
Wavy underlineThe characters are not in the dictionary. They were left out of the physical name
Dotted underlineA synonym or forbidden word was read as the standard word
Italic textThe physical name the dictionary would build differs from the column's current name

Hover over a cell with a mark and an icon appears at its end. Clicking it opens the Review needed menu, which shows the affected words in a table with the New, Mismatch, Related and Antonym columns, and offers items to fix them.

Comparing existing columns with the dictionary

For a column that already exists in the database, typing a logical name changes neither its name nor its type. This keeps documentation from piling up changes waiting to be applied, or from truncating data by shortening a length. Instead, mismatches are marked, and you decide for each column whether to fix it.

  1. Select orders in the ERD and type Order Datetime into the Logical Name cell of the ordered_at column. In logical mode the column name column is hidden by default, so turn it on in the info panel to see the name as well. Result: The column name stays ordered_at, and the logical name turns italic (1).
  2. Click the icon at the end of the cell. Result: A menu opens, and in its table (2) Order and Datetime are checked in the Mismatch column, because the dictionary's abbreviations (ord, dtm) differ from ordered and at in the current name.
  3. To change the name to the standard, click the Rename to ord_dtm item (3). If you are only documenting, do not click it. Result: The column is renamed, and because the column exists in the database, the rename becomes a change waiting to be applied. The domain goes only as far as a suggestion, because agreeing to change the name is not agreeing to change the type. To match the type, choose it yourself in the domain cell.

Fixing from the menu

The Review needed menu shows only what applies to the cell.

ItemWhen it appearsWhat it does
The Register word itemWhen there are characters not in the dictionary. One line per such partEnter the abbreviation and domain on the spot to add the word to the connection's dictionary, and rebuild the physical name of the clicked column. Other columns keep their names
The Standardize words itemWhen a synonym or forbidden word remains in the logical nameChanges the logical name to the standard words. The physical name is not changed
The Rename to ord_dtm itemWhen the physical name the dictionary would build differs from the current nameRenames the column as the dictionary says
The Add antonym column 'End' itemWhen you used a word that has an antonym, and the paired column does not exist yetAdds the paired column right below (for example, End Datetime next to Start Datetime)
The Details itemWhen words were read from the dictionaryShows the details of the words read (abbreviation, domain, related words)
  1. Type Delivery Datetime into the new table. Result: Delivery is not in the dictionary, so it gets a wavy underline, and only dtm remains in the physical name.
  2. Click the icon at the end of the cell (1) and click the Register word item (2). Result: The Add word dialog opens.
  3. Enter the abbreviation DLV in the dialog and click the Add button. Result: The physical name changes to dlv_dtm. The registered word is saved as an edit for the connection only, and the original dictionary is unchanged. To add it to the original as well, edit the dictionary in the manager, or create a new asset with the clone in the data dictionary panel (Assigning to a connection).

Logical names written before the dictionary was assigned, such as those of reverse-engineered tables, are not standardized automatically. Such cells show a dotted underline; fix them with the Standardize words item.

Table names work the same way

The logical name field in the table header is read with the same dictionary. For a new table, typing a logical name changes the name right away; for a table that exists in the database, an icon to rebuild the name appears next to the logical name when the name differs from the dictionary. Clicking the icon renames the table. A table's logical name does not change the table comment in the database.

What's next