id_search#
- Catalog.id_search(values: dict[str, Any], index_catalogs: dict[str, str | IndexCatalog] | None = None, fine: bool = True) Catalog[source]#
Query rows by column values.
In the context of Catalog collections this method will try to find an index catalog for each field name specified in values. If the catalog calling this method is not part of a collection or if it cannot find the index catalog for the fields in the collection specification, explicit index_catalogs for the desired fields can be specified. The index_catalogs argument is a dictionary of field names to HATS index catalog paths or their instances and they take precedence over the catalogs specified in the collection.
- Parameters:
- valuesdict[str, Any]
The mapping of field names (as string) to their search values. Values can be single values or lists of values (but only one list of values is allowed per search). If a list is specified, the search will return rows that match any of the values in the list.
- index_catalogsdict[str, str | HCIndexCatalog] | None, default None
The mapping of field names (as string) to their respective index catalog paths or instance of HCIndexCatalog. Use this argument to specify index catalogs for stand-alone catalogs or for collections where there is no index catalog for the fields you are querying for.
- finebool, default True
If True, the rows of the partitions where a column match occurred are filtered. If False, all the rows of those partitions are kept. Defaults to True.
- Returns:
- Catalog
A new Catalog containing the results of the column match.
- Raises:
- ValueError
If no values were provided for the search. If more than one column contains a list of values to search for.
- TypeError
If index catalog for field is not of type HCIndexCatalog.
Examples
To query by “objid” where an index for this field is available in the collection:
catalog.id_search(values={"objid":"GAIA_123"})
To query by “fieldid” and “ccid”, if “fieldid” has an index catalog in the collection and the index catalog for “ccid” is present in a directory named “ccid_id_index_catalog” on the current working directory:
catalog.id_search( values={"fieldid": 700, "ccid": 300}, index_catalogs={"ccid": "ccid_id_index_catalog"} )
To query for multiple values in a column, use a list of values:
catalog.id_search(values={"objid": [1, 2, 3, ...]})