Post on 13-Feb-2017
Agenda
I. Why documentII. What is database documentationIII. How to document
I. WHYDOCUMENT
Databases are vague
Sample table and column names from real databases:• MTL_SYSTEM_ITEMS_B – Raw materials?• tP – Projects. Who would guess…• BEN_PRTT_RMT_RQST_CTFN_PRVDD - ?• RSRCSECX - ?• ATTRIBUTE5 – Who knows…
https://dataedo.com
Databases are complex
Sample table in Oracle e-Business Suite (ERP)
https://dataedo.com
Databases are large
Number of tables and views in sample applications:• Sample custom enterprise application: 3,000• TETA (HRM): 9,000• Oracle e-Business Suite (ERP): 55,000• SAP (ERP):
130,000!
https://dataedo.com
…but as if addresses had following format:PA_ADW_R_ACT_CMT_B_V.TXN_ADW_NOTIFY_FLAG
Finding a column is like trying to find an apartment in Manhattan
When is it useful?• Software Development• Data Warehousing, BI• Data Analysis, Data Science, Big Bata• Packaged application implementation – ERP, CRM, HRM,
billing etc. • Application Integration (EAI, EII, MDM)• Software/system maintenance• Data Migration• Data Quality• Master Data Management
https://dataedo.com
II. WHAT ISDATABASE DOCUMENTATION
1. Data DictionaryTable: employeeTable holds past, current and future company employees.
Column Data type DescriptionBusinessEntityID int Primary key for Employee records. Foreign key
to BusinessEntity.BusinessEntityID.
NationalIDNumber nvarchar(15) Unique national identification number such as a social security number.
LoginID nvarchar(256) Network login.OrganizationNode hierarchyid Where the employee is located in corporate
hierarchy.
OrganizationLevel smallint The depth of the employee in the corporate hierarchy.
JobTitle nvarchar(50) Work title such as Buyer or Sales Representative.
https://dataedo.com
Relations
https://dataedo.com
Table Role Foreign key column DescriptionDepartments Works in DepartmentID Department where emplyee
People Manager ManagerID Employee superior
JobsDict Job title TitleID Employee job title
StatusesEmployee row can be in following statuses based on dates:• Future – start_date > today or start_date null• Current – start_date <= today and (end_date > today or null)• Past – end_date < today
https://dataedo.com
List of Values
Column DescriptionMaritalStatus M = Married, S = Single, NULL = UnknownActiveFlag 1 = Active, 0 = Inactive
https://dataedo.com
Data Access InterfaceTo modify and fetch data use this:• employee_get – returns specified employee row• employees_get – returns selected employees• employee_insert – use this to insert new employee• employee_update – use this to update employee row• employee_delete – use this to delete employee
https://dataedo.com
Usage
View: employees_active_v
Used by: Employees search form, Active employees report
https://dataedo.com
Data Source
Table: employee
Data source: Employees form, sync_employees
Column SourceMaritalStatus Employees formNationalIDNumber Employees formNumber emp_no triggerScore Data warehouse, calc_employees_scores
https://dataedo.com
Other Metadata
Table: po_headers_all (Purchase orders)
Subject Area: PurchasingOwner: Piotr Kononow
Columnpo_header_idpo_header_number [OBSOLETE]po_header_codeqty Quantityvalue qty * unit_price
https://dataedo.com
Meaningful Descriptions
Instead of this:
Column Descriptionnumber Invoice numberdate Invoice date
https://dataedo.com
Meaningful Descriptions
Do this:
Column Descriptionnumber Invoice autogenerated number, starting from 1 each
year. Number is generated when invoice gets approved.
date Invoice issue date. Null for working copy invoices. Set to today’s date on invoice approval.
https://dataedo.com
III. HOW TODOCUMENT
What tools to use?
• MS Excel, MS Word, Notepad• Database console• Dedicated tool
https://dataedo.com