The vizquery program is a facility to query remotely VizieR. This program is part of the cdsclient package, and can run on any linux/unix platform. It reads the query parameters on its standard input, and writes the results of the query on the standard output in various formats including VOTable or FITSNote: this description is preliminary, and it may happen that all specifications are not fully implemented; if some features are missing or not working, please contact us (click on the enveloppe at the bottom of this page)
Please refer to the cdsclient pages which includes all the details for the installation of vizquery.
Without any argument, vizquery displays a short help:
||Usage: vizquery [-mime={html|ascii|votable|fits|tsv|csv|astrores|xml|acl}] [-get] [-http_header] [-site=site] [asu_constraint|input_file_with_contraints]... (details at: http://vizier.u-strasbg.fr/doc/vizquery.htx ) Sites are: vizier.u-strasbg.fr (cds) (fr) vizier.cfa.harvard.edu (cfa) (us) vizier.hia.nrc.ca (cadc) (ca) vizier.nao.ac.jp (adac) (jp) urania.iucaa.ernet.in (iucaa) (in) data.bao.ac.cn (bejing) (cn) archive.ast.cam.ac.uk (cambridge) (uk) www.ukirt.jach.hawaii.edu (ukirt) (hawaii) www.inasan.rssi.ru (moscow) (ru)
||html ||is the format used by the various browsers like Netscape, Mozilla or Internet Explorer, and presents the results in nicely formatted tables; however such a presentation requires a large amount of bytes, and is not quite easy to interpret by a program.|| ||ascii ||is also meant to be used by browsers, but here tables are presented as column-aligned bytes separated by blanks. It generates less bytes than the html output, but still includes HTML tags like links.|| ||votable ||is the format defined for the Virtual Observatory; its structure is defined in the VOTable Documentation.|| ||fits ||is the (ascii) tabular format defined in the context of the Flexible Image Transport System.|| ||tsv ||is an ascii format where each column is separated from the next one by a tab character (with hexadecimal representation 09, and sometimes named Control-I).|| ||csv ||is a format similar to tsv, but the character used to separated the columns is the semicolon ; Other punctuation characters may be used to separate the columns - by just specifying the punctuation as the mime type: for instance -mime=';' has the same effect as -mime=csv. To separate the columns by a vertical bar, just use -mime='|'.|| ||astrores ||is a mixture of XML and TSV format also known as Astrores; it is the original format developped for the communication to the Aladin integrator.|| ||acl ||is the format required by SkyCat and used e.g. by Gemini tools.
Each line of the input to vizquery may contain the following:
Specifying a Choice of Catalogues: there are several ways of designating catalogues; the fastest is to use the catalog identification assigned in VizieR like -source=I/239/hip_main for the main Hipparcos catalog.
||-source= ||catalog(s) to query (Several catalogs may be specified if separated by a comma or a blank).
Well-known catalog abbreviations may be used - the full list of abbreviations known in VizieR can be listed.|| ||-words= ||names or words of title of catalog. The words are and'ed, i.e. only the catalogues characterized by all the words are selected.|| ||-kw= ||keyword in any of the 3 lists by Wavelength, Mission, or Astronomy.
If several keywords are given on the line, they are or'ed; but if several lines with -kw=value exist, their content is and'ed.|| ||-ucd= ||designation of UCD
The catalogues having one or more columns matching the specified UCD(s) are selected; the * may be used as a wild character, e.g. PHOT_*_B represents a blue photometry which can be in a lot of different photometric systems.
Several -ucd=value can be used to select catalogues having simulteously the properties specified by the UCDs; in other terms, similalry to -kw, UCDs specified on the same line are or'ed, while the different lines are and'ed.|| ||-nosurvey ||restricts the choice to catalogues outside the ``survey'' list of catalogues.|| ||-obsolete ||asks to include the obsoleted versions of catalogues in the set.||
Target Center: the specification of a target requires a center - a position in the sky - and a geometry around the center. Only a circle/annulus, and a rectangular box, are available.
||-c= ||defines the center of the target
There are many possibilities of specifying the center - by object name, position in sexagesimal or decimal degrees. For equatorial positions, remember that a sign must exist before the declination, and that no decimal point in the RA part implies a sexagesimal position (i.e. 15 +12 means 15h+12°, but 15.+12 means 15°+12°, or 1h+12°.|| ||-c.eq= ||defines the equinox of the position given in the -c argument. Note that this parameter is not useful when the target is specified by a name.
Typical examples are -c.eq=B1950 or -c.eq=Gal
The default is -c.eq=J2000|| ||-c.rm= ||defines the radius of the target in arcminutes.
Two numbers may be specified: in the case, the target is an annulus.|| ||-c.rd= ||defines the radius of the target in degrees.|| ||-c.rs= ||defines the radius of the target in arcsec.|| ||-c.bm= ||defines a rectangular box of horizontal/vertical dimensions in arcmin, as e.g. -c.bm=8x6|| ||-c.bd= ||defines a rectangular box in degrees|| ||-c.bs= ||defines a rectangular box in arcsec.||
Output Contents: the contents and order of the result can be specified by the following arguments:
||-meta ||No actual query is performed, only the tables involved in the query are described. This is useful to get an idea of which catalogues exist which share e.g. a keyword. || ||-meta.all ||similar to -meta, but all metadata (details of columns) are listed.|| ||-out= ||specifies the result columns to list in the output; -out= is normally followed by a list of column names (separated by blanks) to be displayed.
The list may contain computed columns for names starting by an underscore (_) with the following conventions:
||_r ||Distance from the target center || ||_x ||Horizontal distance from the target center (East)|| ||_y ||Vertical distance from the target center (North)|| ||_RA(Equinox, Epoch) ||Computed right ascension for a specified frame / equinox / epoch with the standard convention that J2000 represents the FK5/ICRS frame, and B1950 the FK4 frame.The list may also use UCD to designate columns, when a name start by the * (asterisk) (e.g. -out=*ID_MAIN). In addition, the * alone stands for the list of default columns, and the ** stands for the list of all columns. || ||-out.all ||Display all columns (i.e. -out.all is equivalent to -out=**)|| ||-out.add= ||List of columns to add to the standard set, e.g. -out.add=_r lists the distance to the target || ||-out.max= ||Maximal number of rows to retrieve (default is 50)|| ||-out.meta= ||Some options on the descriptions of the columns, as a set of characters referring to the possible additional details; the list may be preceded by + or - for addition or removal of the following elements:
_RA or _RAJ or _RAJ2000 are a shorthand for _RA(J2000,J2000)
_RAB or _RAB1950 are a shorthand for _RA(B1950,B1950) || ||_DE(Equinox, Epoch) ||Computed declination, using the same conventions as _RA || ||_GLON ||Computed galactic longitude || ||_GLAT ||Computed galactic latitude || ||_SGLAT ||Computed supergalactic latitude || ||_SGLON ||Computed supergalactic longitude || ||_1 ||Name of target or input constraint (applies to lists) || ||_q ||Counter of target number (applies to lists) ||
||h ||(header) add the column names || ||u ||(unit) add the units of each column || ||U ||(UCD1) give the UCD1 (default is UCD1+)|| ||2 ||(2UCDs) give the two UCDs (UCD1 and UCD1+)|| ||D ||(Description) adds the description of columns || ||L ||(Links) add the definition of Links (may result in more columns than what was asked)||
The default is huD; to get for instance the 2 UCDs, add -out.meta=+2|| ||-out.form= ||Some options on the output:
||DTD ||(for VOTable output): use the DTD definition rather than the standard XML-Schema || ||bin64 ||(for VOTable output): use a binary 64-encoded output for the data || ||TSV ||(for VOTable output): use a Tab-Separated-Values representation of the data (the Astrores way) || ||groups ||(for VOTable output): use the groups of columns introduced in VOTable1.1|| ||mini ||(for lists): minimize the output, i.e. keep a single table which gathers the results of the list (the list must be applied to a single table) |||| ||-sort= ||Sort order, e.g. -sort=_r to sort by increasing distance to the target. A minus sign before the column name (e.g. -sort=-_r) indicates a decreasing order.|| ||-oc.form ||form of the computed position, as -oc.form=dec for decimal degrees, or-oc.form=sexa for sexagesimal representations ||
The full syntax of the way to specify constraints (what is at the right of the leftmost equal sign) is detailed in the Qualification Syntax.
Note that lists are more generic than just lists of targets: the -c= expresses that the constraints given in the list concern the position. But other possibilities exist: an example below queries a list of Hipparcos stars.
The examples use the delimiter ====End to indicate to the shell where the standard input starts and ends. This delimiter can be changed to any other valid delimiter (word excluding the characters meaningful to the shell like spaces, asterisks, brackets, questions marks, ampersand, ...); alternatively if the query arguments are saved in a file named e.g. myQueryArguments , the standard shell redirection can be used and the first example could be written
vizquery -mime=tsv < myQueryArguments
The -meta.all alone just list all metadata available outside any catalog context - which consists essentially of the keywords.vizquery -mime=tsv <<====End -meta.all ====End
vizquery -mime=csv <<====End # Query All Columns of 2MASS and Tycho-2 Catalogues around HD 226868 -source=2MASS,Tycho-2 -out.all -out.add=_r -sort=_r -c=HD 226868 -c.rm=2 ====End
vizquery -mime=csv <<====End # Retrieve Hiparcos stars closer than 20pc (Plx > 50mas) # and order the results by decreasing parallax # (i.e. increasing distance from the Sun) -source=HIP/hip_main -out.max=9999 -oc.form=dec -out=Plx, _RAJ2000, _DEJ2000, HIP, Vmag, B-V -sort=-Plx Plx=>50 ====End
vizquery -mime=votable <<====End ### Example of a list of Targets for vizquery usage ####################### -source=USNO-B1 # VizieR uses catalog numbers -- would work also with #-source=I/284 -out.max=9999 #-out.add=_1 asks to insert my target as the first output column -out.add=_1 # I need the distance of the found objects, too. -out.add=_r # Be as concise as possible -- don't create a new table for each target -out.form=mini # My output looks better sorted by increasing distance to each target. -sort=_r # Max distance to the target: 1arcmin -c.rm=1 # Now comes the list of my targets: -c=<<====MyList # Some random position in (RA,Dec) 123.5-12.68 # The First Quasar 3C 273 # The only supernova brighter than 6mag SN 1987A # 2 bright stars used for checking alpha Cen alpha UMi ====MyList ====End
vizquery -mime=votable <<====End ### Example of a list of Targets for vizquery usage ####################### -source=HIP/hip_main #-out.add=_1 asks to insert my Hipparcos number as leftmost column. -out.add=_1 # Be as concise as possible -- don't create a new table for each star -out.form=mini # Get all parameters of the Hipparcos main table -out.all # Now comes the list of my Hipparcos numbers: HIP=<<====myHIPsample # In fact, I want just Hipparcos stars 1 to 10, # 101 to 110, 1001 to 1010, 10001 to 10010, and 100001 to 100010 1..10 101..110 1001..1010 10001..10010 100001..100010 ====myHIPsample ====End