From 6b3d5960f7537dcd4ea0dd2a3a1c797964711446 Mon Sep 17 00:00:00 2001 From: David Rodriguez Date: Thu, 13 Feb 2025 18:40:10 +0000 Subject: [PATCH 1/2] Some schema and documentation improvements --- astrodbkit/__init__.py | 4 ++++ astrodbkit/schema_example_felis.yaml | 13 ++++++++++++- docs/index.rst | 21 +++++++++++++++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) 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..158f86f 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 start 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 ============= From ab1d8305d5ed0a896d12f571fe122913edbf1dc2 Mon Sep 17 00:00:00 2001 From: David Rodriguez Date: Thu, 13 Feb 2025 13:46:40 -0500 Subject: [PATCH 2/2] Update docs/index.rst Co-authored-by: Kelle Cruz --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 158f86f..632e23a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -519,7 +519,7 @@ 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 start general parameters. +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.