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