Introduction

OpenSkyQuery is a facility that allows users to compare astronomical catalogs, finding positional cross-matches subject to any other conditions or constraints the user wishes to define based on the data in the catalogs. The catalogs/databases that are available for use are shown on the Query Screen on the left side, under the title Nodes.

The primary interface utilizes SQL, the Structured Query Language, with a few extensions specialized for astronomical data. SQL is a standard computer language for accessing and manipulating databases. You may wish to learn more about SQL by reviewing some on-line tutorials, such as http://www.w3schools.com/sql/default.asp. However, the document below explains the three basic SQL expressions you need to know to make good use of OpenSkyQuery, and after seeing a few examples, you will be generating your own queries in a short time!

Making a query

Sample Queries

The sample queries provide an introduction to the basics of SQL and simple extensions that support astronomical databases. The sample queries are found on the right side of the Query page. The first one, XMatch/Region, looks like this:

SELECT o.objId, o.ra,
    o.dec, o.r, o.type,
    t.objId, t.ra, t.dec
FROM
    SDSS:PhotoPrimary o, TWOMASS:PhotoPrimary t
WHERE XMATCH(o, t) < 3.5 AND
    Region('CIRCLE J2000 181.3 -0.76 6.5') AND
    o.type = 3

It is easiest to understand this query if we start in the middle, with the FROM statement. The SQL FROM statement specifies which databases to use. Here we select two databases, SDSS (Sloan Digital Sky Survey) and TWOMASS (Two-Micron All Sky Survey). These databases have a number of separate tables in them. The FROM statement says that we will use the tables called PhotoPrimary (primary photometric data) from each database. And, rather than having to type SDSS:PhotoPrimary everytime we want to refer to this table, we will create an alias for it, "o", and similarly use the alias "t" to refer to TWOMASS:PhotoPrimary.

Now, back to the first part of the query, the SELECT statement. The SELECT statement tells OpenSkyQuery which columns in the databases to show in the results. This statement says to show the objID (object identification), ra (right ascension), dec (declination), r (r-band magnitude), and type (object type code) from the SDSS:PhotoPrimary table, and the objID, ra, and dec from the TWOMASS:PhotoPrimary table. As we will see later, these tables have many other columns and any of them could be added to the SELECT statement.

Finally we have the WHERE statement, which is used to set conditions on the comparison between the two databases. The clause XMATCH is an OpenSkyQuery extension to SQL that compares astronomical object positions taking into account the positional uncertainties in each position. The clauseXMATCH(o,t)<3.5 specifies that all objects that have positional coincidences at a confidence level of 3.5 sigma or better will be included. Objects that have lower probability of being spatially coincident are ignored. See http://openskyquery.net/Sky/SkySite/help/algo.aspx for a more detailed explanation of the cross-match algorithm.

The WHERE statement also puts a condition on location in the sky using the REGION clause, which limits the area of the cross-match to a circle centered on right ascension 181.3 degrees, declination -0.76 degrees, and radius 6.5 arcmin). Finally, only those objects that are of type 3 (extended objects) in SDSS are included.

If you click on the little "i" in the circle to the right of the example, a brief explanation will be shown as a reminder of the above.

Run the query by clicking the Submit button at the bottom of the middle panel. The right-hand panel shows the status of the query processing, and after a moment or two should report that the query is complete. If you click View you see a table that contains the columns from the SELECT statement for all objects that satisfied the WHERE clauses. You can save this table in one of several formats: HTML, CSV (comma-separated values), VOTable, or DataSet. Or, you can click Plot on the results panel and the table will be shown using the VOPlot tool.

Sample Query Xmatch/Region 2

The second example query, XMATCH/Region 2, adds two additional columns to the results table, t.j_m (TWOMASS J-band magnitude) and o.i (SDSS i-band magnitude). Additional constraints have been specified in the WHERE statement, limiting the results to objects with SDSS i-band magnitudes brighter than 21 (o.i<21), objects with TWOMASS J-band magnitudes brighter than 18 (t.j_m<18), and objects where the TWOMASS source is at least 2 magnitudes brighter than the SDSS source (o.i-t.j_m>2). These conditions are connected with AND statements, so that only objects that meet all criteria simultaneously will be shown in the results. Criteria can also be combined with OR statements. The effect of this WHERE statement is to show extended objects in SDSS and TWOMASS that are well above their sensitivity limits and that are also very red, i.e., extremely red galaxies.

Sample Query - Three Node Match

The third example query, Three Node Match, shows a positional cross-match on three databases at once. The FROM statement includes the USNO-B database, abbreviated as "p". The WHERE statement invokes the XMATCH function, but note the arguments are (o, t, !p). The exclamation point means NOT, so that this query finds objects that match in position in SDSS and TWOMASS and do NOT have counterparts in USNO-B!

Sample Query- Brown Dwarf Search

Build your own query

If you wish to Xmatch one or more catalogues just click on the (+) sign near the node name on the left of the screen. This should switch your query screen to build mode. Form here you may click on the "select" word to add more colums or on a table to add more conditions or selections. Try clicking on the differnt parts of the query - it will help you build a valid ADQL statement. At anytime you may switch to edit mode by clicking edit on top of the panel. In edit mode you may paste in any query (like the one above) and then click build to have the syntax checked and make it interactive. bThis shouls switch your query screen to build mode. Form here you may click on the "select" word to add more columns or on a table to add more conditions or selections. Try clicking on the differnt parts of the query - it will help you build a valid ADQL statement. At anytime you may switch to edit mode by clicking edit on top of the panel. In edit mode you may paste in any query (like the one above) and then click build to have the syntax checked and make it interactive.

Here is a Flash demo of the query builder

Upload

You may upload a table of data using the Import Screen get to it by clicking on this link or by using the menu bar. On the import screen you may name your table. You need to supply the format e.g. Comma/Space/Tab separated for text or VOTable for XML. We also need to know if the RA and DEC are in decimal or sexagesimal. You may upload a file from your disk or Paste data directly in the provided space on this screen. The only limitation on this is the web request length but in practicality tables much larger that 2k rows will probably cause problems.

Once this data is loaded if you return to the Query Screen you will now have MyData as a new node. This may be included in any query including Xmatch queries. Please note that MyData does not support regions, you may include a region clause in a query with MyData and it will be applied to other nodes in the query but the MyData node ignores the statement.