cobtools.query package

Submodules

cobtools.query.query_gaia module

This module provides wrapper objects around the astroquery.gaia module to facilitate querying the Gaia archive in different ways.

Classes

SingleSourceQuery

Abstract base class that defines the interface for querying the Gaia archive for a single source. Subclasses must implement the query_str property and can utilize the query_result method to retrieve results.

SingleSourceFullGaiaQuery

Concrete implementation of SingleSourceQuery that retrieves all available columns for a given source_id from the Gaia main source table.

Examples

Query the Gaia DR3 archive for a specific source:

>>> query = SingleSourceFullGaiaQuery(
... source_id=123456789, data_release="dr3"
... )
>>> results = query.query_result()
>>> print(results)

Notes

The module requires the astroquery library to be installed and configured with access to the Gaia archive. Queries are executed via the Gaia TAP service and results are returned as astropy Table objects.

It also uses the functools.cached_property decorator (Python 3.8+) to cache the Gaia job object. cobtools depends on Python 3.10+, so this is compatible.

See also

astroquery.gaia

Gaia archive query interface

astropy.table.Table

Table data structure for query results

query_gaia.py

class cobtools.query.query_gaia.SingleSourceFullGaiaQuery(source_id: int | str, data_release: str = 'dr3')[source]

Bases: SingleSourceQuery

Concrete implementation of SingleSourceQuery for querying the Gaia archive.

This class retrieves the full set of columns for a given source_id from the main Gaia source table.

query_str : str

The ADQL query string to retrieve all columns for the specified source_id.

property query_str: str

The ADQL query to retrieve all columns for a given source_id from the Gaia archive.

Returns:

The ADQL query string.

Return type:

str

class cobtools.query.query_gaia.SingleSourceNSSQuery(source_id: int | str, data_release: str = 'dr3', table_name: str = 'nss_two_body_orbit')[source]

Bases: SingleSourceQuery

Concrete implementation of SingleSourceQuery for querying the Gaia Non-Single Star (NSS) catalogs.

This class retrieves all columns for a given source_id from the specified NSS catalog. Currently, data_release is restricted to “dr3” since the NSS catalogs are only available in DR3.

Parameters:

  • source_id (str or int) – The source_id to query.

  • data_release (str) – Must be “dr3” for NSS queries since the NSS catalogs are only available in DR3.

  • table_name (str) – The specific NSS catalog table to query. Valid options are: - “nss_two_body_orbit” - “nss_acceleration” - “nss_non_linear_spectro”

query_str : str

The ADQL query string to retrieve all columns for the specified source_id from the Gaia NSS catalog.

property job: Job

The Gaia job object that will be used to execute the query.

Returns:

The astroquery.utils.tap.model.job.Job object representing the Gaia query job.

Return type:

Job

property query_str: str

The ADQL query to retrieve all columns for a given source_id from the Gaia NSS catalog.

Returns:

The ADQL query string.

Return type:

str

class cobtools.query.query_gaia.SingleSourceQuery(source_id: int | str, data_release: str = 'dr3')[source]

Bases: ABC

Abstract base class for querying the Gaia archive.

This class provides a framework for querying the Gaia archive. Subclasses must implement the query_str property to define the ADQL query string. The query_result method is implemented in the base class and can be used as-is or overridden by subclasses to customize the behavior.

Parameters:

  • source_id (str | int) – The source_id to query. Accepts an integer, or any value convertible to integer by Python int(…) semantics (for example, strings with surrounding whitespace or a leading +). Float inputs are rejected.

  • data_release (str) – The Gaia data release to use.

source_id_obj

A SourceID object that encapsulates the source_id and data_release information.

Type:

SourceID

Properties
----------
source_id

Read-only. The numeric Gaia source_id. Forwards to self.source_id_obj.source_id.

Noindex:

Type:

int

data_release

Read-only. The Gaia data release string (e.g. "dr3"). Forwards to self.source_id_obj.data_release.

Noindex:

Type:

str

query_str

The ADQL query string for the specified source_id.

Noindex:

Type:

str

job

Cached property that launches the Gaia query job and returns the astroquery.utils.tap.model.job.Job object. Handles errors if the query does not complete successfully.

Noindex:

Type:

Job

query_result() → Table[source]

Retrieve the query results as an astropy.table.Table object.

Noindex:

Raises:

  • ValueError – If source_id is not an integer or a string containing only numeric characters. If data_release is not one of the valid options (“dr1”, “dr2”, “edr3”, “dr3”, “dr4”, “dr5”).

  • RuntimeError – If the Gaia query job does not complete successfully or if there is an error while fetching the query results.

property data_release: str

Backwards-compatible access to the Gaia data_release string.

This read-only property forwards to self.source_id_obj.data_release.

Returns:

The Gaia data release (e.g. "dr3").

Return type:

str

property job: Job

The Gaia job object that will be used to execute the query.

Returns:

The astroquery.utils.tap.model.job.Job object representing the Gaia query job.

Return type:

Job

query_result() → Table[source]

Query the Gaia archive for the specified source_id.

Returns:

The query results as an astropy.table.Table object.

Return type:

Table

abstract property query_str: str

The ADQL query string to retrieve data for the specified source_id.

Returns:

The ADQL query string.

Return type:

str

property source_id: int

Backwards-compatible access to the numeric Gaia source_id.

This read-only property forwards to self.source_id_obj.source_id.

Returns:

The Gaia source identifier.

Return type:

int

class cobtools.query.query_gaia.SingleSourceUsefulInfoQuery(source_id: int | str, data_release: str = 'dr3')[source]

Bases: SingleSourceQuery

Concrete implementation of SingleSourceQuery for querying a subset of useful columns from the Gaia main table.

Parameters:

  • source_id (str or int) – The source_id to query. See SourceID for valid formats.

  • data_release (str) – The Gaia data release to query. See SourceID for valid options.

  • Properties

  • ----------

  • query_str (str) – The ADQL query string to retrieve a specific subset of useful columns for the specified source_id from the Gaia main table.

property query_str: str

The ADQL query string to retrieve data for the specified source_id.

Returns:

The ADQL query string.

Return type:

str

Module contents