Mapped Documentation
In this case you may reuse the Business Name and Definition of an already documented object (quite commonly a term in a glossary) via a semantic mapping link.
You may:
- Document using one or more existing terms
- Create a new term and document with it
- Create a new term based upon existing terms used for documenting the object and thus normalizing the term documentation.
Term documentation is implemented as part of the Glossary Model Type in MANAGE > Metamodel as Defines and Is Defined By.
Mapped Documentation Using Existing Terms
Steps
From the object page
- Navigate to the object page for the object you wish to document. Then click the Overview tab.
- Click on the pencil (Edit) icon in the Documentation section.
- In the Mapped Documentation section of the dialog, click on the pencil (Edit) icon.
Talend Data Catalog automatically searches with the physical name of the object. You may wish to remove that search filter if you wish to find a different term or one that is spelled differently.
- If it did not find the term you are looking for, remove the search filter.
- Search or navigate to the term you wish to use to document this object and select the term.
- Click OK.
The Business Name (next to the physical name) and Business Description in the Term Documentation section now inherit from the term selected.
From the Semantic Flow tab
- Navigate to the object page for the object you wish to document. Then click the Semantic flow tab.
- Click Edit Documentation.
- From here it is the same steps as on the Overview tab.
Example
Navigate to the object page for the column AddressID in the Address table of the Accounting > MITI-Finance-AR model.
Click on the pencil (Edit) icon in the Documentation section.
In the Mapped Documentation section of the dialog, click on +ADD.
We want to reuse an existing term in the Finance glossary and map this term to this object so that it infers its Name and Business Definition from the term. One may do all of this in one step, and then re-use the term for other objects.
However, the first time that you want to create such a semantic link to an object in a particular model (the Accounting model in this case), you must have a semantic mapping repository object to contain these semantic links.
Click the Select object icon.
The recommended objects are presented, which are a list of all the semantic mapping models in this configuration.
If there is already such a semantic mapping object that you wish to reuse, you may do so from the list. However, these are rather specific semantic mapping model for glossary to glossary links and another for links to Tableau only. Thus, we can create a new semantic mapping.
Create a new semantic mapping using the hyperlink above that is named Finance Glossary to Imported Models.
The SOURCE MODELS is specified as the Finance glossary, so it will always suggest terminology. However, in order to work for any imported model, no DESTINATION MODELS have been defined.
Now, return to the AddressID object and click the Select object icon again. Then in the Mapped Documentation section of the dialog, click on +ADD again. Finally, click the Select object icon, again.
This time, you are presented with the new semantic mapping model and can use it here.
Change the search text to “Address ID”, i.e., add a space character.
Select the term Address ID from the list and click OK. Then click CLOSE.
The imported object AddressID now reuses the Name “Address ID” and Definition from that term.
Mapped Documentation with a New Term
Steps
From the object page
- Navigate to the object page for the object you wish to document. Then click the Overview tab.
- Click on the pencil (Edit) icon in the Documentation section.
From the Semantic Flow tab
- Navigate to the object page for the object you wish to document. Then click the Semantic Flow tab.
- Click Edit Documentation.
For Either Case
- In the Mapped Documentation section of the dialog, click +ADD.
- Enter the:
- OBJECT PARENT which is the parent term or glossary which will contain the new term.
- NAME of the term
The NAME will be pre-populated with any human readable name based upon the physical name.
- DESCRIPTION of the term which will be inherited as the Term Documentation for the object.
- Click the magic wand icon to pick a DESCRIPTION to reuse from inferred definitions
- Click OK.
The Business Name (next to the physical name) and Business Description in the Term Documentation section now inherit from the term selected.
Example
Navigate to the object page for the column AddressType in the Address table of the Accounting > MITI-Finance-AR model.
Click on the pencil (Edit) icon in the Documentation section.
We want to create a new term in the Finance glossary and map this new term to this object so that it infers its Name and Business Definition from the term. One may do all of this in one step, and then re-use the term for other objects.
Go to the Browse tab, navigate to the term named Terminology and right-click and select New > Term.
Un-check the Mandatory fields only checkbox.
Enter the text as follows:
Click OK.
The new term is now available and selected as the mapped object.
Click OK.
Click CLOSE.
The Documentation section is now populated.
The Name and Business Description are now inherited from the new term.
You may remove this documentation and the term relationship by again clicking the pencil icon.
Term Documentation with a New Term from Existing Terms - Normalization
Steps
From the object page
- Navigate to the object page for the object you wish to document. Then click the Overview tab.
- Click on the pencil (Edit) icon in the Documentation section.
From the Semantic Flow tab
- Navigate to the object page for the object you wish to document. Then click the Semantic tab.
- Click Edit Documentation.
For Either Case
- In the Term Documentation section of the dialog, click + CREATE TERM.
- Enter the:
- OBJECT PARENT which is the parent term or glossary which will contain the new term.
- NAME of the term
The NAME will be pre-populated with any human readable name based upon the physical name.
- DESCRIPTION of the term which will be inherited as the Term Documentation for the object.
- Click the magic wand icon to pick a DESCRIPTION to reuse from inferred definitions
- Click OK.
The Business Name (next to the physical name) and Business Description in the Term Documentation section now inherit from the newly created term. In addition, a
Example
Navigate to the object page for the column AddressID in the Address table of the Accounting > MITI-Finance-AR model.
There are two terms related to this imported object with the Is Defined As relationship. Thus, this object is not uniquely defined.
In order to normalize the term documentation, click on the pencil (Edit) icon in the Documentation section.
In the Term Documentation section of the dialog, click on CREATE TERM.
Specify the NAME and DESCRIPTION as follows:
Click OK.
The Term Documentation section is now normalized and there is only one definition.
Then click CLOSE.
The Name and Business Description are now inherited from the new term.
Go to the object page for the newly created term and note the See Also link back to the two pre-existing terms that you create this new one for
There are See Also relationships to the previously defining terms.
Mapped Documentation Other Than Glossary Based
You may also reuse the Name and Definition of a object, such as in a data modeling imported model.
Bulk Mapped Documentation
Steps
- Create or open a worksheet of the objects you wish to bulk document.
- Select (click, shift-click or ctrl-click) one or more objects.
- Click the More options icon in the <number> selected indicator and select Edit.
- Specify one or more terms in the is Defined By in OBJECT RELATIONSHIPS.
- Click OK.
Example
Create or open a worksheet of CATEGORY of type Dataset > Data Attributes with the Search string “GLAccountNumber”.
Click Columns and add the Documentation, Inferred Documentation and Mapped Documentation and the is_Defined_By columns to the worksheet.
Click outside the Columns dialog.
As can be seen, many of the objects found in the search are already defined, mostly through inference. In particular, there is Dimensional DW > dbo > GLAccount > GLAccountNumber which is semantically mapped with a definition from a term of the same name with spaces (GL Account Number).
Let’s take a look at this column, term and how inference works in this case.
Click the term and go to the Semantic Flow tab and select Usage. Also, select the Diagram presentation and expand to columns level.
Now, we can see all the pass-through lineage (light grey lines) and these are all column level objects which infer their documentation from this term. By mapping a term with a good business definition to one object in the data flow, we see that many objects up and downstream infer their documentation. Thus, strategically documenting (semantically mapping in this case) a central set of columns/field in a warehouse or data lake, and you have documented the entire architecture (at least that portion with pass-through lineage).
We can now finish documenting the objects in the worksheet in bulk by selecting the Mapped Documentation column for those objects without anything in the Documentation column.
Select (click, shift-click or ctrl-click) one or more rows.
Click the More options icon in the 6 selected indicator and select Edit.
Specify one or more terms in the is Defined By in OBJECT RELATIONSHIPS.
Click OK.
Click OK. Refresh the list.
