diff --git a/astrodbkit/__init__.py b/astrodbkit/__init__.py index c59abce..c6f5412 100644 --- 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 index 9424a0d..6f9d183 100644 --- 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 index 94ab52a..632e23a 100644 --- 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 =============