The Filter and Query Language
The Kepler Data Explorer has been designed with two goals in mind: to make access to the Kepler Database fun and straightforward, and to enable users to quickly build customizable, powerful, and useful filters and views of the dataset. This latter, more advanced feature, is made possible through a simple query language that is built into the table and plotter components. Advanced users who would like to leverage the full flexibility of the Kepler Data Explorer should peruse this section of the documentation to familiarize themselves with the query language.
The query language is used in two distinct contexts: to construct filters and to combine and transform planet properties to create new quantities. The former is used in the Table and Plotter to select a subset of planets to view, the latter is used in the plotter to produce scatter plots and histograms of combinations of planet properties and in the table to construct custom columns.
Perhaps the simplest way to introduce the query language is to present some examples. If you would rather jump to a list of available operations and functions skip to below.
The filter:RPLANET < 2
selects all planets with radii smaller than 2 earth radii. Note that the Column ID
RPLANETis used to refer to the planet radius. The table in the column definitions help page can be used to lookup column IDs for all KOI properties in the Kepler dataset.
The filter:19 < RA AND RA < 19.5 AND 40 < DEC AND DEC < 42
selects all planets with coordinates lying in the range 19<Right Ascension<19.5 and 40<Declination<42. The query language supports the three basic boolean operations:
NOT. The equivalent notation
!can also be used.
The filter:PER[yrs] >= 1
selects all planets with orbital periods (
PER) greater then or equal to 1 (Earth) year. This filter illustrates the use of basic unit conversion in the query language. The default unit for orbital period is days, however an alternate set of units can be requested by passing the relevant unit ID in square brackets. Of course, the chosen unit must be valid -- see the section on units below for more details and for a table of unit IDs.
Of course this filter is equivalent toPER >= 365
Alternatively one could scale the PER property directly:PER/365 >= 1
in fact, the Exoplanet Query Language allows for arbitrary mathematical combinations of property IDs and numbers. Addition (
+), division (
-), multiplication (
*), division (
/), and exponentiation (
^) are all supported.
The filter:UPER/PER<=1e-5 AND UPER>0
selects all planets with periods accurate to within 1 part in 10-5. Note that planet properties can be combined mathematically enabling us to take the ratio of the uncertainty in the orbital period (
UPER) to the period (
PER). We include
UPER>0to ensure that planets without period uncertainties are not included in the cut.
selects all KOI systems that are confirmed planetary candidates. To select KOI that are both confirmed and strong candidates one can combine the
STRONGcolumns:CONFIRMED || STRONG
or even!(MODERATE || NEEDS_FOLLOWUP)
alternatively, one can use the
VETTING_FLAGcolumn as follows:VETTING_FLAG <= 2
this works because confirmed planets have
VETTING_FLAG = 1and strong candidates have
VETTING_FLAG = 2
The filter:N_OBJ >= 3
selects all KOI systems containing 3 or more KOIs. It is important to understand that the KOI is the fundamental object stored in the Kepler database -- there are no stellar objects; rather, all stellar system information is stored in KOI objects such that KOI orbiting the same star have the relevant stellar information duplicated amongst them. Thus to select all systems containing 3 or more KOI one must select all KOI with N_OBJ >= 3.
One can emulate stellar searches by first restricting the Database to pick out the first KOI for each system (those KOI's with KOI = XX.01). One way to do this would be to use the filter:KOI_OBJ = 1
This matches all objects with KOI ID's of the form XX.01.
KOI_OBJpicks out the object component of the KOI ID. More intuitively, however, one can use the
FIRST_OBJECTcolumn to quickly select the first KOI subset of the database. Since
FIRST_OBJECTis a boolean flag the filter is simply:FIRST_OBJECT
The (complicated) filter:sqrt((RA[deg]-19*15)^2+((DEC[deg]-41)*cos(RA[rad]))^2)<1
selects all planets that lie (roughly) within one degree of the coordinate RA=19h, DEC=41°. This is accomplished by computing the angular distane in degrees between each planet's RA and DEC coordinate and the point (285, 41) using the spherical coordinate metric. Note the use of the
cosfunctions. The query language supports a number of common mathematical functions.
Example Custom Properties
All of the above examples combine and compare planet properties in order to ultimately produce a true or false cut on each planet in the Kepler database. This behavior is appropriate in the context of filters. The query language is also used, however, when constructing custom scatter and histogram plots in the Plotter and custom columns in the table. In this context, KOI properties can be combined mathematically in order to yield a new numerical quantity for each KOI. This quantity can then be plotted against other numerical quantities, or presented in the table. Here are some examples:
approximates the planetary mass (in earth mass units) of the KOI assuming an earth-like density.
computes the KOI's orbital velocity in units of meters-per-second.
Supported Operations and Functions
The following operations and functions are supported by the query language.
Supported Mathematical Operators
Supported Comparison Operators
Supported String Comparison OperatorsNote: all string comparisons are case-insensitive.
|CONTAINS||Subset matching: returns true if any part of the string on the left hand side matches the string on the right hand size||VETTING_STATUS CONTAINS "Candidate"|
|==||Identical matching: returns true if the left hand side and right hand side match exactly||VETTING_STATUS == "Strong Candidate"|
Supported Boolean Operators
|&&, AND||Logical and|
|||, OR||Logical or|
|!, NOT||Logical not|
|asin(x)||Inverse Trigonometric Sine, returns radians|
|acos(x)||Inverse Trigonometric Cosine, returns radians|
|atan(x)||Inverse Trigonometric Tangent, returns radians|
|atan2(y,x)||C-like arctangent, takes two arguments and returns radians|
|sin(x)||Trigonometric Sine, accepts radians|
|cos(x)||Trigonometric Cosine, accepts radians|
|tan(x)||Trigonometric Tangent, accepts radians|
|ceil(x)||Takes the ceiling of the passed in number|
|floor(x)||Takes the floor of the passed in number|
|round(x)||Rounds the passed in number|
|log(x), ln(x)||Natural Logarithm (i.e. ln)|
|log10(x)||Log base 10|
|sqrt(x)||Square root function|
|max(x,y)||Returns the larger of x and y|
|min(x,y)||Returns the smaller of x and y|
|pi||pi = π = 3.14159....|
|true||The boolean value |
|false||The boolean value |
|NaN||The special not-a-number value |
The query language allows for basic unit conversions for columns that have associated units.
|Physical Class||Unit||Unit ID|
|Astronomical Units (AU)||au|