The ``vizquery'' program

5.1 The vizquery program

The vizqueryprogram 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 FITS

Note: 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)

5.1.1 Package Installation

Please refer to the cdsclient pages which includes
all the details for the installation of vizquery.

-mime defines the output format in a way similar to the
VizieR Output Preferences;
a very short outline of the various formats is:

||html ||is the format used by the various browsers like Firefox,
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(the corresponding cgi is /viz-bin/votable)||
||fits ||is the ascii tabular format defined in
the context of the Flexible Image Transport System(the corresponding cgi is /viz-bin/asu-fits).||
||binfits ||is the binary tabular format defined in
the context of the Flexible Image Transport System (BINTABLE extension)
(the corresponding cgi is /viz-bin/asu-binfits).||
||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)
(the corresponding cgi is /viz-bin/asu-tsv).||
||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(the corresponding cgi is /viz-bin/asu-xml).||
||acl ||is the format required by SkyCat and used e.g. by
Gemini tools
(the corresponding cgi is /viz-bin/asu-acl).||
||text ||is a simple aligned asci text output (text/plain mime type)
(the corresponding cgi is /viz-bin/asu-txt).||

-site defines which VizieR installation is to be queried;
the list of available sites is displayed above. Any of the parenthesied
words can be used, e.g.
vizquery -site=cadc directs the query to the Canadian installation.
The default is -site=cds.

-list specifies lists of targets or
contraints one one parameter stored in a text file
(see details below)

The other arguments may be

either some constraint using the ASU conventions,
which is an alternative to the usage of constraints
included in the input
described in the next section;
typical examples
are -source=2MASS to specify the 2MASS
catalogues, -c=12:23+24:12,rm=20
to express a circular target of 20arcmin around the
J2000 position 12:23+24:12, or Vmag=10..12
to express a condition on a range of values of the column
named Vmag in a range [10,12].

or the name of a file which contains all query constraints following the
ASU conventions (see below).
This file
must be the last argument, and its name cannot start by a
minus (-) or contain an equal sign (=).

When no constraint is given as arguments or via a file,
the query specifications are assumed to be in the
standard input
(i.e. typed at the terminal or included in the script with the
Unix <<sentinel convention).

5.1.3 Input to vizquery

The input_file_with_contraints (standard input by default if
no contraint is given to the vizquery ) specifies what to query in
VizieR: which catalog(s), which position to look at,
what to display, how many records, etc...
written as 1 query argument per line.
The query definitions follow the ASU protocol, using the name=value paradigm;
submitting list of targets is detailed below.

Each line of the input to vizquery may contain the following:

a comment – a line starting by the # symbol.

a text to echo – a line starting by a dot . or a colon :

name=value specifications;
there are a few conventions about name:

a name starting by a dash or minus sign -
represents a parameter which is not an actual column
of any catalog – VizieR effectively does not
accept any column name starting by special symbols
like + - * / . Typical examples of such names
are -source to specify a catalog, or -c
to specify a target on the sky.

a name starting by an asterisk*
represents a column designated by its
Unified Content Descriptor (UCD); UCDs
represent a classification of the different
kinds of parameters is aimed at assigning
generic names of all parameters contained in any
catalog. A preliminary list of UCDs
is accessible.
Note that the UCD tree is still in development;
it will most likely change in the near future,
and is not yet fully operational.

other names are assumed to designate an actual column
of a catalog – e.g. Plx is the column of the
Hipparcos catalog
which contains the trigonometric parallax.

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.||
||-pos ||restricts to tables containing celestial positions||
||-phot ||restricts to tables containing well-defined photometry||
||-nosurvey ||restricts the choice to catalogues outside the
``survey'' list of catalogues.||
||-obsolete ||asks to include the obsoleted versions of catalogues
in the set.||
||-corr= ||correlation for a fine-grain selection of tables:

-corr=pos restricts to tables having a position;
-corr=name=col_name restricts to tables
having the specified col_name among its columns;
-corr=PK=col_name restricts to tables
having the specified col_nameand this column
is a primary key of the table;
-corr=FK=col_name restricts to tables
having the specified col_nameand this column
is a foreign key of the table;

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.||
||-box= ||defines a rectangular box using IAU-conventions, e.g.
J0000-00 for a box
in J2000 coordinates containing the positions
having their RA between 0h0m and 0h1m
and their declination between 0° and –1°
This convention is valid also with other coordinate systems:
Bhhmm...±dd... (B1950 position),
Glon...±lat... (galactic position),
S... (supergalactic)
and E (ecliptic).
Finally a box may also be represented by a qbox
value, the systems of cells used to access by positions
(described briefly in the
qbox man page)||

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.||
||-meta.max= ||specifies the maximal number of catalogs to be listed
(the default is 500) ||
||-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, in addition to standard column names:

computed columns: names starting
by an underscore (_)

||_r ||Distance from the target center ||
||_x ||Horizontal distance from the target center (East)||
||_y ||Vertical distance from the target center (North)||
||_pa ||Position angle (North through East) of vector from the target center (degrees)||
||_key ||The column representing a key (identifier) of a row
(typically the recno counter when that one
exists) ||
||_ID ||a string which identifies a row, in the form
name=value
(typically recno=record_counter)||
||_RA(Equinox, Epoch) ||Computed right ascension for a specified
frame / equinox / epoch with the standard conventions:
ICRS represents the ICRS frame,
J2000 represents the FK5(J2000)/ICRS frame, and
B1950 the FK4(B1950) frame._RA _RAJ or _RAJ2000
are a shorthand for _RA(J2000,J2000)_RAJ() is a shorthand for _RA(J2000)(keeping the epoch)_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 (from 1) of target number (applies to lists) ||
||_V ||A http link to the row being edited. _V may be followed
by a text which will be used in the link. ||
||_sed0 ||Minimal details to build an SED
(Spectral Energy Distribution): edit the columns containing
magnitudes or fluxes in well-identifier filters, wavelengths
or frequencies. ||
||_sed1 ||In addition to _sed0, compute the flux (in Jy)||
||_sed3 ||Present the SED as 3 vectors: (1) frequencies (GHz),
(2) fluxes (Jy) and (3) errors on fluxes (Jy) ||
||_sed4 ||Present the SED as a set of formatted SED points;
one point is formatted as GHz=Jy[errJy]${col}[filter]
e.g. 241.77e+3=31.3[0.8]e-3${Jmag}[2MASS:J]
for a flux in the 2MASS J-band,
or 353.00=8.91[0.21]${S}@{Freq} for a flux from the
column S and the frequency from the column Freq.
||

ucd-specified columns: names starting
with an asterisk * and followed by an
UCD
like e.g. *meta.id;meta.main

columns with links to images:
*Mime(image/fits)

the list of the default columns:
specified by a single asterisk *

the list of all columns:
specified by a double asterisk **

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

||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=d for
decimal degrees, or-oc.form=s for sexagesimal representations.
An optional M (Main) can be added to specify that
the UCD qualification main main is added to the
computed position (by default this main
qualification is attached to the original position) ||

Joining tables:
Two or more tables can be combined or joined into a single table;
some details and examples can be found in the
join documentation.
The following argments are specific to joins:

||-joincol ||specifies the column used in the join (the name must be
shared among the tables involved).||
||-outjoin ||specifies the table.column of the referent column
in the case of outer joins.||

Issuing several queries:
Independant queries can be issued in a single request,
using a -go separator. More control can be specified in the
case of votable output:

-go/ closes the current RESOURCE
(the following query will start with a new RESOURCE)

-go+ keeps the current TABLE
(the following query appends its result to the current table,
if their schemas are compatible)

-go. closes the current TABLE
(the following query starts a new TABLE, but keeps the RESOURCE
if these are identical).

5.1.4 Constraints on columns

Any column (including the computed columns) can be constrained,
e.g. specifying a range of values, of matching some pattern for the
The generic way of specifying a contraint is
column_name=constraint, e.g. Vmag=<12.5
to specify that only rows for which the column named Vmag
is less than 12.5 are to be selected.

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.

5.1.5 Using lists in vizquery

There are 2 ways to specify a list of targets in vizquery :

with the -list argument
(introduced in July 2010)

Long lists of contraints on one parameter – typically a list of
targets (positions on the sky) or values asked in one column of
a table – can be stored in a plain ascii file and referred in
the -list argument.

Assuming that the file myTargets.txt contains the list of targets
(set of positions or object names, 1 per line; the semi-colon (;)
can be used for in-line comments)
the command

vizquery -source=PPMXL -out.add=_r -list=-c=myTargets.txt

will deliver the sources found in the PPMXL catalog
around each of the positions specified, with their distance
from the sources specified in the myTargets.txt file.

If a constraint other than the position is supplied in a file,
the name of the column of the table corresponding to the parameter
is specified after the list, as in the example below

the traditional way consists in embedding the
list of targets in the input stream with the
following conventions:

the list comes after the other qualifications, e.g.
enter contraints on fluxes (e.g. Jmag=11..14.5)
before giving the list of targets

the list of targets starts by a line -c=<<====myName
where myName can be replaced by a name of your choice
(a suggestion: use the name of the file containing the targets)

each subsequent line, until the a line starting by
====myName, contain a target name (e.g. M99)
or position (e.g. 01 23 45.6 +10 20 30), or a comment;
there are possibilities of using sexagesimal or decimal values,
see the various possibilities of
specifying the center.
Comments are lines starting by a hash (#); blank lines
are ignored.

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.

5.1.6 Examples

The examples are shown in 2 dialects: either a single command line
possibly referencing a file, or with
the use of a 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 writtenvizquery -mime=tsv < myQueryArguments

Query the catalogues em 2MASS and USNO-A2
2arcmin around the object HD 226868, with distances to the target:

Query the USNO-B1 around a list of targets, and get the
result as a VOTable

The traditional way is:

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 ; random position
# 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

A probably simpler way, assuming that the file MyList.txt contains what
is between the markers ====MyList, would be

Query all parameters of the Hipparcos main catalog, and give the
result as a VOTable for a sample of Hipparcos stars.

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

The simpler way would be, if myHIPsample.txt contains the text
between the myHIPsample markers: