Help on Vizier-like expressions

The KM3NeT Open Data supports search expressions modelled after what CDS' Vizier service provides. Our implementation is not yet complete. If you need a given feature, please let us know.

The rough idea is that you can specify the values you search for with certain operators, depending on the type of the field you are matching against.

Vizier-like expressions for numeric values

Overview

For numeric expressions, you can use the following operators:

Examples

Grammar

For those into such things, here is the grammar we currently use to parse numeric expressions (the base nonterminal is expr).

	preOp    ::= "=" |  ">=" | ">" | "<=" | "<"
	rangeOp  ::= ".."
	pmOp     ::= "+/-" | "\xb1"  (this is the ± character)
	orOp     ::= "|"
	andOp    ::= "&"
	notOp    ::= "!"
	commaOp  ::= ","

	preopExpr  ::= [preOp]  floatLiteral
	rangeExpr  ::= floatLiteral rangeOp  floatLiteral
	valList    ::= floatLiteral { commaOp floatLiteral }
	pmExpr     ::= floatLiteral pmOp floatLiteral
	simpleExpr ::= rangeExpr | pmExpr | valList | preopExpr

	notExpr    ::= [notOp] simpleExpr
	andExpr    ::= notExpr {andOp + notExpr}
	expr       ::= andExpr {orOp + expr}

floatLiteral is a usual C decimal integer or float literal.

Vizier-like expressions for dates

Overview

Dates support the same operators as numeric operands, except that the "error" in expressions with +/- is a simple float (in days). Dates are given in one the the VO's preferred ISO formats, i.e., YYYY-MM-DD or YYYY-MM-DDTHH-MM-SS. You can also give simple floating point numbers as dates, which will be interpreted as Julian years if between 1000 and 3000, as MJD if between 1e4 and 1e5, and JD if between 2e6 and 4e6. If you hit midnight when giving JD (i.e., number.5) or MJD (number.0), DaCHS will interpret the specification as “whole day” and expand the range accordingly.

In the VO, timezones are frowned upon. Hence, you will usually deal with UTC or a related time scale (like TT). For the reference positions, you will have to inspect the metadata.

Times without dates are not yet supported. In general, we try to interpret dates without times in a sensible way; for instance, if you just give a date, all records with a timestamp on that date will match.

Examples

See also the examples for numeric expressions.

Grammar

The grammar is identical to the one of numeric expressions, except that floatLiteral is dateLiteral with the exception of pmExpr that is

pmExpr := dateLiteral pmOp floatLiteral

here. The dates themselves currently follow the regular expression [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]. This will be relaxed in the future.

Vizier-like expression for strings

Overview

Note: Contrary to what Vizier does, the default on string expressions on this site is to match expressions literally (i.e., the default operator is == rather than ~).

Some of the operators below work on patterns. A pattern contains the meta characters [, ], *, and ?; all others are "normal" characters matched literally. The * matches zero or more characters, the ? exactly one; characters in square brackets match any character enumerated within them. You can use ranges like "A-Z" within square brackets. If the first character in the square brackets is a caret (^), all characters except the ones listed are matched.

The following operators can be used when matching strings – when we talk about literals as operands, metacharacter interpretation is suppressed (i.e., the strings are matched literally), otherwise we talk about patterns.

Note that both patterns and literally interpreted strings must match the whole data field. This is substantially different from the usual regular expression engines (but corresponds to what you may know from filename patterns).

Examples

Here is a table of expressions and their matches:

ExpressionData
M4eM4epm4eA4pO4pM*m|ax,a=x
M4eX        
=x         
== =x        X
!= =xXXXXXXXX 
==M4eX        
=~m4eX X      
=~m4         
~*XXXXXXXXX
~m*XXX  XX  
M*     X   
!~m*   XX  XX
~*p X XX    
!~*pX X  XXXX
~?4p   XX    
~[MO]4[pe]X X X    
=[MO]4[pe]X   X    
>O  X X XX 
>O5  X   XX 
>=m  X   XX 
<M   X    X
=|M4e| O4p| x,aX   X  X 
=,x,a,=x,m|a      X X

Maybe some comments are in order:

  1. =x matches nothing since the leading = is interpreted as an operator ("match as pattern case-insensitively"), and there is nothing matching the pattern x in the sample (in this case , only x and X would match).
  2. == =x is the simplest way to search for "=x" – its analogues work for all other metacharacters as well.
  3. =~m4 matches nothing, because the pattern has to match the entire string, and all strings in the sample have some annexes to their variations of m4.
  4. M* only matches "M*" since the default on our system is literal matching. This expression would have behaved completely differently on Vizier.

Grammar

The following grammar describes the parsing of string expressions:

	simpleOperator   ::= "==" | "!=" | ">=" | ">" | "<=" | "<"
	simpleOperand    ::= Regex(".*")
	simpleExpr       ::= simpleOperator + simpleOperand
	
	commaOperand     ::= Regex("[^,]+")
	barOperand       ::= Regex("[^|]+")
	commaEnum        ::= "=," commaOperand { "," commaOperand }
	exclusionEnum    ::= "!=," commaOperand { "," + commaOperand }
	barEnum          ::= "=|" barOperand { "|" + barOperand }
	enumExpr         ::= exclusionEnum | commaEnum | barEnum

	patLiterals      ::= CharsNotIn("[*?")
	wildStar         ::= "*"
	wildQmark        ::= "?"
	setElems         ::= CharsNotIn("]")
	setSpec          ::= "[" + setElems + "]"
	patElem          ::= setSpec | wildStar | wildQmark | patLiterals
	pattern          ::= patElem { patElem }

	patternOperator  ::= "~" | "=" | "!~" | "!"
	patternExpr      ::= patternOperator pattern

	stringExpr       ::= enumExpr | simpleExpr | patternExpr | nakedExpr