Query Methods for new Catalogs

[snbianco]

This PR significantly expands the CatalogCollection and Catalogs querying framework to support new MAST catalogs, improve catalog validation, and provide more robust and user-friendly query behaviors.

Key Enhancements

1. Implementation of query methods

• Expanded API for query_criteria:
  • Supports new filtering behaviors, including negation, numeric ranges, wildcard string matching, and mixed OR/AND logic.
  • Validates spatial query support per catalog.
  • Adds parsing for region, coordinates, and objectname with cleaner checks.
  • Handles column selection and ordering more robustly.
  • Integrates new metadata structure for RA/Dec columns and supported ADQL region functions.
  • query_region and query_coordinates now call query_criteria in their implementation. We are keeping these functions for backwards compatibility.

2. Support for New Default Catalogs

• DEFAULT_CATALOGS mapping lists default catalogs for known collections.
  • Hard coding is not ideal, but I think the increase in user-friendliness outweighs the questionable design here. Ideally, VO-TAP will eventually have some sort of endpoint for this.
  • If the collection is not listed in the mapping, the default catalog is the first catalog found that is not part of the tap schema.

3. Improved Catalog Verification

• _verify_catalog now:
  • Returns the validated catalog name (instead of just checking).
  • Supports case-insensitive and no-prefix matches (e.g., meanobjectview → dbo.MeanObjectView).
  • Provides clearer error messages and intelligent closest-match suggestions.

4. Backwards Compatibility Improvements

• Deprecate version, page, and pagesize parameters.
• Detect if a user is trying to pass in an old collection name (like panstarrs or gaia), warn them, and then query with the new collection name.
• Detect if a user is trying to pass a collection in under the catalog parameter. If they are, warn them and use the catalog given as the collection. This is particularly relevant as we are changing the name of the parameter from catalog to collection.

[Copilot]

Pull request overview

This PR implements comprehensive query methods for the new MAST Catalogs framework, enabling users to query catalog collections with improved validation, spatial queries, and backwards compatibility features.

Key Changes:

• Implemented query_criteria, query_region, and query_object methods with support for spatial queries, filtering, sorting, and column selection
• Added DEFAULT_CATALOGS mapping to provide default catalog selections for known collections
• Enhanced _verify_catalog and _verify_collection methods with case-insensitive matching, no-prefix lookup, and helpful error messages

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 12 comments.

File	Description
astroquery/mast/collections.py	Implements the main query methods (query_criteria, query_region, query_object) with ADQL generation, region parsing, criteria formatting, and backwards compatibility handling
astroquery/mast/catalog_collection.py	Adds DEFAULT_CATALOGS mapping and updates _verify_catalog to return validated catalog names with improved matching logic

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[snbianco]

@dr-rodriguez @astrojimig @cpparts @AlexReedy @sedonaprice

[sedonaprice]

Hi @snbianco --- I know the PR isn't completed yet, but I think it would be best to be explicit that spherical sky regions are required for region searches.

Also, it might be the case that users provide a spherical Region in a non-ICRS frame. Thus lines 680-687 of collections.py might need checks to ensure / transform the region into the right frame.

[snbianco]

Thanks @sprice! Agreed on being explicit — I’ve updated docstrings to clarify the exact types expected when inputting a region.

On the frame question: the current implementation should already handle non-ICRS spherical regions correctly. For both CircleSkyRegion and PolygonSkyRegion, we explicitly access .icrs on the region center/vertices before constructing the ADQL geometry, which ensures the coordinates are transformed into the ICRS frame regardless of the input frame. If a region can’t be transformed to ICRS, Astropy will raise an error, which would be appropriate in that case.

[sedonaprice]

I would still argue we should be extra explicit and say that ~region.CircleSphericalSkyRegion and the like instances are required (though still not in main, but hopefully imminently!). Implicitly, ~region.CircleSkyRegion is planar (requires a WCS to understand what "contains" is, because it has to be mapped to pixel coordinates on a plane), while the spherical sky regions are spherical and don't depend on the planar projection choices.

This would be a chance to consider which type of geometry (spherical vs planar) for a region is truly intended --- but for cone searches I really think everyone would intend it to be "actually on the sky", hence ~region.CircleSphericalSkyRegion

[snbianco]

I see! So this is something that's being added to regions, but isn't in main or a release yet? I'm assuming so because I don't see those particular classes in the docs.

[sedonaprice]

Yeah, it's an open PR (promising initial feedback and waiting for review): astropy/regions#618