Some schema and documentation improvements (#94)

* Some schema and documentation improvements * Update docs/index.rst Co-authored-by: Kelle Cruz <[email protected]> --------- Co-authored-by: Kelle Cruz <[email protected]>
astrodbtoolkit · Feb 13, 2025 · 05f7b5d · 05f7b5d
1 parent 9a87456
commit 05f7b5d
Show file tree

Hide file tree

Showing 3 changed files with 37 additions and 1 deletion.
diff --git a/astrodbkit/__init__.py b/astrodbkit/__init__.py
@@ -34,6 +34,10 @@
     "Versions",
     "Parameters",
     "Regimes",
+    "ParameterList",
+    "AssociationList",
+    "CompanionList",
+    "SourceTypeList",
 ]
 # REFERENCE_TABLES is a list of tables that do not link to the primary table.
 # These are treated separately from the other data tables that are all assumed to be linked to the primary table.

diff --git a/astrodbkit/schema_example_felis.yaml b/astrodbkit/schema_example_felis.yaml
@@ -35,6 +35,7 @@ tables:
       datatype: string
       length: 1000
       description: Publication description
+      ivoa:ucd: meta.note
 
 
   - name: Telescopes
@@ -56,6 +57,7 @@ tables:
       datatype: string
       length: 30
       description: Publication reference; links to Publications table
+      ivoa:ucd: meta.ref
 
     constraints:
       - name: Telescopes_reference_Publications_name
@@ -158,8 +160,9 @@ tables:
     - name: comments
       "@id": "#Sources.comments"
       datatype: string
-      length: 1000
+      length: 100
       description: Free-form comments on this Source
+      ivoa:ucd: meta.note
 
 
     indexes:
@@ -251,6 +254,7 @@ tables:
       datatype: string
       length: 30
       description: Photometry band for this measurement
+      ivoa:ucd: instr.bandpass
     - name: ucd
       "@id": "#Photometry.ucd"
       datatype: string
@@ -261,37 +265,44 @@ tables:
       datatype: double
       description: Magnitude value for this entry
       fits:tunit: mag
+      ivoa:ucd: phot.mag
     - name: magnitude_error
       "@id": "#Photometry.magnitude_error"
       datatype: double
       description: Uncertainty of this magnitude value
       fits:tunit: mag
+      ivoa:ucd: stat.error;phot.mag
     - name: telescope
       "@id": "#Photometry.telescope"
       datatype: string
       length: 30
       description: Telescope, mission, or survey name; links to Telescopes table
+      ivoa:ucd: instr.tel
     - name: instrument
       "@id": "#Photometry.instrument"
       datatype: string
       length: 30
       description: Instrument name; links to Instruments table
+      ivoa:ucd: instr
     - name: epoch
       "@id": "#Photometry.epoch"
       datatype: double
       description: Decimal year
       fits:tunit: yr
+      ivoa:ucd: time.epoch
     - name: comments
       "@id": "#Photometry.comments"
       datatype: string
       length: 1000
       description: Free-form comments for this entry
+      ivoa:ucd: meta.note
     - name: reference
       "@id": "#Photometry.reference"
       datatype: string
       length: 30
       description: Publication reference; links to Publications table
       nullable: false
+      ivoa:ucd: meta.ref
 
     indexes:
       - name: PK_Photometry

diff --git a/docs/index.rst b/docs/index.rst
@@ -509,6 +509,27 @@ These options can facilitate the creation of robust ingest scripts that are both
 and that can take care of validating input values before they get to the database.
 
 
+Advanced Database Considerations
+================================
+
+Here we provide useful tips or guidance when working with **AstrodbKit**.
+
+Handling Relationships Between Object Tables
+--------------------------------------------
+
+Becuase **AstrodbKit** expects a single primary table, object tables that point back to it, and any number of reference tables, it can be difficult to handle relationships between object tables. 
+
+As an example, consider the scenario where you want to store companion information to your sources, such as a table to store the relationship with orbital separation and a separate one to store general parameters. 
+You may be calling these CompanionRelationship and CompanionParameters, respectively. 
+If you want to link them together, you might decide to specify that the companion in the CompanionRelationship table should be a foreign key to the CompanionParameters table.
+**However**, this will run into issues on database saving/loading as the output JSON files will no necessarily load tables in the order you expect. 
+You might find it attempting to load CompanionParameters only to find that CompanionRelationship hasn't been loaded yet all the foreign keys are broken.
+
+The better approach is to define a lookup table that will store the companion identifiers which will be used as the foreign keys. 
+For example, a CompanionList table that both CompanionParameters and CompanionRelationship can refer to. 
+This would be a reference table, similar to Telescopes or Publications, while CompanionParameters and CompanionRelationship would be object tables that require tying back to a specific source in the Sources table.
+Essentially, this is normalizing the database a bit further and serves to avoid some common issues with foreign keys.
+
 Reference/API
 =============