Merge branch 'master' of hgwdev.cse.ucsc.edu:/data/git/kent
[kent.git] / src / hg / makeDb / schema / joiner.doc
1 INTRODUCTION
2
3 The .joiner file describes relationships between tables.
4 In particular it groups together fields in different tables
5 that refer to the same identifier.  The first field in the group
6 normally contains all instances of that identifier, while subsequent
7 fields may contain only a subset.  In relational database terms
8 the first field in the group is the primary key, and other fields
9 are foreign keys.
10
11 The joiner file is somewhat more flexible than foreign keys in
12 a relational database.  It allows fields that contain comma separated
13 (or other simply-separated) lists of identifiers.  It allows an
14 identifier to contain a constant prefix or suffix in one field,
15 and not in another.  It allows tables to be split up for performance
16 reasons (such as the per-chromosome tables common at UCSC) but still
17 to be viewed logically as the same table.  It allows you to specify
18 the identifier relationships in multiple databases simultatiously.
19 It also can describe cases where it can be worthwhile to do a join
20 on two fields, but where both fields contain some of their own unique
21 identifiers.
22
23 The program 'joinerCheck' performs some automatic checking on joiner
24 files.  Joiner files are also intended to be used in generating automatic
25 documentation and database browsing tools.
26
27 The joiner file is a line-oriented format.  In some cases blank lines
28 are also significant.  Lines starting with # are treated as comments
29 and ignored.  There are two primary types of record in a joiner file -
30 a 'set' statement which creates a variable, and an identifier statement.
31
32 THE SET STATEMENT
33
34 The set statement is quite simple:
35    set varName value
36 Here varName should start with a letter, and can be followed by any
37 number of letters and numbers.  The value extends to the end of the
38 line.  Once a variable is defined this way, $varName afterwards
39 will be replaced with the value from the set line.  Variable can
40 be defined in terms of other variables.  In some cases it may be
41 necessary to use ${varName} rather than $varName if doing a substitution
42 in the middle of another word.
43
44 THE IDENTIFIER STATEMENT
45
46 The identifier statement defines an identifier shared across tables.
47 The basic format is one line containing the identifier name and attributes,
48 a quoted comment line, a line for the field that serves as the primary
49 key for the identifier, and then a line for each other field that shares
50 the identifier.  The field lines describe the field in database.table.field
51 format, and then attributes if any of the field.  The database component
52 may be a comma separated list if the field is in more than one database.
53 A blank line indicates the end of the identifier statement.
54 Here's an example
55
56    identifier customerId typeOf=personId
57    "This is the id of someone who has bought something from us."
58         sales.customer.id
59         sales.sale.customer
60         sales.return.customer
61         corperate.customer.id chopBefore=CID:
62         legal2004,legal2003.liability.plaintiff chopBefore=CID: chopAfter=.
63         legal2004,legal2003.recall.notified chopBefore=CID: chopAfter=. comma
64
65 Identifier Line Attributes:
66   typeOf - indicates this is a subset of a parent type of identifier.
67            Joins between fields in this identifier and preceding generations 
68            of identifiers are often fruitful.  
69      value: parent identifier.  
70   external - indicates this identifier is defined outside of our own databases
71      value: name of organization that defines identifier
72   fuzzy - indicates that while in many cases the identifier will be shared
73           between the listed fields, the relationship is informal. In 
74           particular the first field is not expected to contain all 
75           instances of the identifier.  
76      value: n/a
77   dependency - indicates that all tables mentioned in field lines below are
78           dependent on the first table mentioned.
79      value: n/a
80
81 Field Line Attributes:
82   comma - the field contains a comma separated list of the identifier.
83      value: n/a
84   separator - the field contains a list of the identifier.
85      value: a single character list separator.
86   chopBefore - the field contains some prefix that needs to be chopped off
87                before it is considered as an identifier.  If the prefix
88                is missing then no chopping occurs.
89      value: a search string. Everything before the first instance of
90             this search string (including the search string itself) is
91             considered prefix, and is removed before joining.
92   chopAfter - the field contains some suffix that needs to be chopped off
93               before it is considered as an identifier
94      value: a search string. Everything after the last instance of
95             this search string (including the search string itself) is
96             considered suffix, and is removed before joining.
97   indexOf - valid only for lists.  This indicates that the identifier
98             is actually the position (zero based) of the item in the list
99             rather than item itself.
100      value: n/a
101   dupeOk - used to indicate that duplicate identifiers are allowed in the
102            first field. - valid only on primary key, not on secondary keys
103      value: n/a
104   minCheck - used to allow some identifiers not to be in primary key.
105      value: A number between 0.0 and 1.0 that indicates the minimum ratio of
106             identifiers in the field that are in the primary key.
107   full - used to show that every key in the primary key should also occur in 
108          this field
109      value: n/a
110   unique - used to show that every key in the primary key occurs at most once
111            in this field
112      value: n/a
113   splitPrefix - used to lump together tables that share a common prefix
114                 into a single logical table.
115      value: Prefix string that may include SQL wildcard characters.  A
116             popular one at UCSC is "chr%\_" (the underscore is escaped
117             because we want a literal match for _, not the SQL wildcard).
118   splitSuffix - used to lump together tables that share a common suffix
119                 into a single logical table.  May be used with splitPrefix.
120      value: Suffix string that may include SQL wildcard characters.  
121   exclude - used to exclude a particular identifier from having to be in
122             primary key.  There may be multiple exclude attributes for a field.
123      value: identifier to exclude.  The empty string may be excluded with
124             a exclude= (that is following the equal immediately with a space).
125
126   
127 IDENTIFIER MACROS
128
129 In some cases there may be multiple instances of a set of
130 interrelated tables.  At UCSC an example of this is the 
131 chains and nets that describe a pairwise alignment.  To
132 avoid having to have a separate identifier for each pair
133 of species there is a small macro expansion facility built
134 in. Here's an example:
135
136 identifier chain[Mm3,Rn2]Id
137 "Link together chain info"
138     $gbd.chain[].id 
139     $gbd.chain[]Link.chainId 
140     $gbd.net[].chainId
141
142 This is expanded to one identifier for each item in the
143 comma-separated list inside of square brackets as so:
144
145 identifier chainMm3Id
146 "Link together chain info"
147     $gbd.chainMm3.id 
148     $gbd.chainMm3Link.chainId 
149     $gbd.netMm3.chainId
150
151 identifier chainRn2Id
152 "Link together chain info"
153     $gbd.chainRn2.id 
154     $gbd.chainRn2Link.chainId 
155     $gbd.netRn2.chainId
156
157 EXCLUDED DATABASES
158    The comma-separated database lists typically are set up with
159    variables, such as $gdb in the above examples.  It's possible
160    to exclude a database from such a list.  To exclude the 'mm4' database
161    but include everything else in $gbd, you'd specify:
162        $gbd,!mm4
163    It is possible to exclude more than one database this way,  and the
164    ! items can be at any position in the list.
165
166
167 OTHER STATEMENTS
168
169 There's a number of other statements that are typically used just
170 once or twice in a joiner file.
171
172 exclusiveSet - This is used to indicate that only one out of a group 
173     databases should be considered at one time.  At UCSC this is used 
174     to group together all of the genome/assembly specific databases so that
175     spurious links are not generated between them.  The syntax of
176     this is a line starting with the word 'exclusiveSet' and followed
177     by a comma-separated list of databases.
178
179 databasesChecked - This keyword is followed by a comma-separated list of
180     all databases that should be checked by the joiner file.
181
182 databasesIgnored - This is followed by a comma-separated list of databases
183     not checked by the joiner file.  The joinerCheck program will complain 
184     about any databases in the system that are not in either the 
185     databaseChecked or databaseIgnored list.  This is just to help keep
186     databases from slipping under the radar, since generally you will want
187     to add a new database to various places in the joiner file.
188
189 dependency - This line indicates that a table depends on other tables.
190     The joinerCheck program will make sure that the last update date on
191     the table is after any of the tables it depends on.  The syntax is
192     just a list of database.tables.  The first table is the dependent table
193     and the rest are the ones it depends on.  Note that the 'dependency'
194     attribute on an identifier line can also specify dependencies.
195
196 tablesIgnored - This statement describes tables that are not checked.
197     The joinerCheck program will complain about tables in the system
198     that are not in any of the identifiers, and not in the tablesIgnored.
199     This is to keep new tables from falling through the cracks.
200     The syntax of this is a line starting with "tablesIgnored" and
201     followed by a comma separated list of databases, and then 
202     a line for each table.  The table names may include the
203     SQL wildcard '%' (which is equivalent to the '*' wildcard in
204     most file systems.)  The statement is terminated by a blank line.
205