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 format¹ 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:

• = tests equality
• != tests non-equality
• > greater than (does not work for string parameters)
• < less than (does not work for string parameters)
• >= greater or equal than (does not work for string parameters)
• <= less or equal than (does not work for string parameters)

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

• cone('object_name', 'search_radius')

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('ra', 'dec', 'search_radius')

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.

• object_name

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

Additional datasets and flags

• is_ulx – boolean flag set to true if source is included into Walton (2011) ULX catalog
• is_cv – boolean flag set to true if source is included into Ritter (2014) CV catalog
• is_lmxb – boolean flag set to true if source is included into Ritter (2014) LMXB catalog
• is_agn – boolean flag set to true if source is classified as AGN by Lin (2012)
• is_star – boolean flag set to true if source is classified as star by Lin (2012)
• has_spectrum – boolean flag set to true if source has detections with extracted spectra
• has_tseries – boolean flag set to true if source has detections with extracted timeseries

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

• M82 – select sources in 1 arcmin vicinity of M82 center
• 00:06:03.386 63:40:46.75 or 00 06 03.386 63 40 46.75 or 1.5143 63.6796 – search 1 arcmin vicinity of sexagesimal or decimal coordinates
• cone('M31', '1deg') AND sc_det_ml < 100 – select faint X-ray sources not further than 1 degree from M31 center
• is_ulx = true AND n_detections > 2 – select ULXs which were detected more than once
• iauname IN {"3XMM J053406.7+220337", "3XMM J053406.6+220438"} – select specific sources by their IAU names
• srcid IN {200068101010001, 200114501010001} – select specific sources by their source IDs (useful for larger subsets)
• is_cv = true AND has_spectrum = true – select cataclysmic variables that have extracted spectra
• is_lmxb = true AND has_tseries = true – select low-mass X-ray binaries that have extracted timeseries
• det_ep_8_flux > 1e-10 AND det_var_flag = true – select sources that include detections brighter than 1e-10 erg/s/cm2 in 0.2–12 keV band with their variability flag set to true
• det_obs_id = '0139760101' AND det_src_num = 1 – select source that has this particular detection in one of the observations