Query language

Basic syntax

At this website it is possible to filter X-ray sources on the catalog and diagrams pages using simple boolean expressions query language which mimics syntax of WHERE clause in SQL language. One can also download query result from the catalog page in machine-readable format1 by clicking one of the Download links on the top right after applying desired filter.

The language consists of arbitrary number of expressions combined together using AND or OR clauses. Expression usually has the following structure (square brackets mean optional clauses):

parameter operator value [AND | OR [NOT] expression] [, …]

where parameter is the name of any X-ray source catalog property present in the database. There is no unit specification so the actual query compares the data with user input value in the default database units. See the 4XMM-DR10 documentation for the list of available source catalog columns (source catalog with its 45 columns is usually called slim catalog to distinguish it from the detections catalog with its 336 columns).

Operator can be any comparison operator from SQL-like languages:

Value in expression can be any string in double or single quotes, integer or float number in decimal notation with the point as a decimal separator. Value must correspond to parameter datatype, i.e. one can't compare string and float number. Use keyword NOT before the expression to negate it.

Slightly different syntax for expression is employed for testing substring inclusion in parameters of a string type:

"substring" IN parameter_string

Another alternative tests for presence of desired substring(s) as a separate word(s) in parameter_string:

{"substring1" [, "substring2" [, ...]]} IN parameter_string

which is often equivalent of the query "substring1" IN parameter_string AND "substring2" IN parameter_string, though not exactly.

Please also keep in mind that you have flexibility to change places of parameter and value in expressions and the overall language is case-insensitive.

Special functions

Make cone search in the catalog with specified radius around object. object_name is a quoted string with an object name to be resolved through the CDS Simbad service and search_radius is a quoted string in a format of value with units, e.g. 1.0deg, 1arcmin, 15arcsec

Cone search the catalog around known coordinates ra and dec with specified radius search_radius. ra and dec can be quoted colon-separated strings in sexagesimal notation, or unquoted float numbers. search_radius is same as in the cone search function above.

Unquoted object name without any other conditions is rewritten to cone('object_name', '1arcmin')

Additional datasets and flags

Query by detection attributes

Query language operates on the source table, whereas a source can have several individual observations called detections. But you can also retrieve sources by using their constituent detection attributes prepending them with prefix det_, for example query

det_obs_id = "0112570401" and det_ep_8_flux > 1e-14

will return all sources that have at least one detection in observation 0112570401 and that detection have 0.2-12 keV flux above 1e-14 erg/s (ep_8_flux column of detections table). For the full list of detection table columns see the 4XMM-DR10 documentation.

Example queries

  1. CSV, VOTable and FITS formats are supported.